prompture 0.0.32.dev1__tar.gz → 0.0.33.dev1__tar.gz

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

@@ -57,4 +57,8 @@ OPENROUTER_MODEL=openai/gpt-3.5-turbo
 # 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
+
+# AirLLM Configuration
+AIRLLM_MODEL=meta-llama/Llama-2-7b-hf
+AIRLLM_COMPRESSION=

prompture-0.0.33.dev1/CLAUDE.md

@@ -0,0 +1,74 @@
+# CLAUDE.md
+
+This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
+
+## Project Overview
+
+Prompture is a Python library for extracting structured JSON output from LLMs, with schema enforcement, Pydantic model integration, TOON (Token-Oriented Object Notation) input/output conversion, and multi-provider driver support. Published on PyPI as `prompture`.
+
+## Build & Development Commands
+
+```bash
+# Install in development mode
+pip install -e ".[test]"
+
+# Run all tests (uses DEFAULT_MODEL from tests/conftest.py)
+python test.py
+
+# Run tests with pytest directly
+pytest
+
+# Run integration tests (require live LLM access)
+pytest --run-integration
+# or: RUN_INTEGRATION_TESTS=1 pytest
+
+# Run a single test file
+pytest tests/test_core.py
+
+# Run a single test
+pytest tests/test_core.py::TestCleanJsonText::test_basic_json
+
+# Skip integration tests when credentials are missing
+TEST_SKIP_NO_CREDENTIALS=true python test.py
+
+# Build distribution
+python -m build
+
+# CLI entry point
+prompture run <spec-file>
+```
+
+There is no configured linter or formatter.
+
+## Architecture
+
+### Module Layout
+
+- **`prompture/core.py`** — Primary business logic. All extraction functions live here: `ask_for_json()` (low-level schema enforcement), `extract_and_jsonify()` / `manual_extract_and_jsonify()` (text-to-JSON), `extract_with_model()` / `stepwise_extract_with_model()` (Pydantic-based), `extract_from_data()` / `extract_from_pandas()` (TOON input), `render_output()` (raw text formatting).
+- **`prompture/drivers/`** — One module per LLM provider (openai, claude, google, groq, grok, azure, ollama, lmstudio, openrouter, local_http, huggingface, airllm). Each driver implements `generate(prompt, options)` returning a standardized response with token/cost metadata.
+- **`prompture/drivers/__init__.py`** — Central `DRIVER_REGISTRY` dict mapping provider name to factory lambda. `get_driver_for_model("provider/model")` parses the string and instantiates the right driver. `get_driver("provider")` is the legacy interface.
+- **`prompture/tools.py`** — Utilities: JSON/TOON text cleanup, type conversion (shorthand numbers, multilingual booleans, datetimes), field schema generation, custom `LogLevel` enum (not stdlib logging).
+- **`prompture/field_definitions.py`** — Thread-safe global field registry with 50+ predefined fields, template variable substitution (`{{current_year}}`, `{{current_date}}`), and Pydantic Field generation via `field_from_registry()`.
+- **`prompture/settings.py`** — Pydantic-settings `Settings` class loading provider API keys/endpoints from `.env`.
+- **`prompture/discovery.py`** — `get_available_models()` auto-detects models from configured providers (static pricing tables + dynamic Ollama endpoint query).
+- **`prompture/runner.py`** — Spec-driven test suite runner for cross-model comparison.
+- **`prompture/validator.py`** — JSON schema validation via jsonschema with fallback.
+
+### Key Patterns
+
+- **Model strings** use `"provider/model"` format (e.g., `"ollama/llama3.1:8b"`, `"openai/gpt-4"`). The provider prefix routes to the correct driver.
+- **Driver responses** always include metadata: `prompt_tokens`, `completion_tokens`, `total_tokens`, `cost`, `raw_response`.
+- **Output formats**: JSON (default) and TOON (experimental, for compact output). Controlled via `output_format` parameter.
+- **TOON input conversion** uses `python-toon` and `tukuy` packages to reduce token usage by 45-60% when sending structured data to LLMs.
+
+### Testing
+
+Tests live in `tests/`. Integration tests that call live LLMs are marked with `@pytest.mark.integration` and skipped by default. The default test model is set in `tests/conftest.py` as `DEFAULT_MODEL`. Shared fixtures and assertion helpers (`assert_valid_usage_metadata`, `assert_jsonify_response_structure`) are in `conftest.py`.
+
+### Configuration
+
+Provider API keys and endpoints are configured via environment variables loaded from `.env` (see `.env.copy` for the template). The `Settings` class in `settings.py` manages all provider config.
+
+### Versioning
+
+Uses `setuptools_scm` for automatic version from git tags. The `VERSION` file contains the current dev version.

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 0.0.32.dev1
+Version: 0.0.33.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Home-page: https://github.com/jhd3197/prompture
 Author: Juan Denis
@@ -29,6 +29,8 @@ Requires-Dist: tukuy>=0.0.6
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: airllm
+Requires-Dist: airllm>=2.8.0; extra == "airllm"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/prompture/__init__.py

@@ -13,7 +13,7 @@ from .core import (
     extract_from_pandas,
     render_output,
 )
-from .drivers import get_driver, get_driver_for_model, OpenAIDriver, LocalHTTPDriver, OllamaDriver, ClaudeDriver, LMStudioDriver, AzureDriver, GoogleDriver, GroqDriver, OpenRouterDriver, GrokDriver
+from .drivers import get_driver, get_driver_for_model, OpenAIDriver, LocalHTTPDriver, OllamaDriver, ClaudeDriver, LMStudioDriver, AzureDriver, GoogleDriver, GroqDriver, OpenRouterDriver, GrokDriver, AirLLMDriver
 from .tools import clean_json_text, clean_toon_text
 from .field_definitions import (
     FIELD_DEFINITIONS, get_field_definition, get_required_fields, get_field_names,
@@ -87,6 +87,7 @@ __all__ = [
     "GroqDriver",
     "OpenRouterDriver",
     "GrokDriver",
+    "AirLLMDriver",
     # Discovery
     "get_available_models",
 ]

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/prompture/drivers/__init__.py

@@ -8,6 +8,7 @@ from .google_driver import GoogleDriver
 from .groq_driver import GroqDriver
 from .openrouter_driver import OpenRouterDriver
 from .grok_driver import GrokDriver
+from .airllm_driver import AirLLMDriver
 from ..settings import settings
 
 
@@ -54,6 +55,10 @@ DRIVER_REGISTRY = {
         api_key=settings.grok_api_key,
         model=model or settings.grok_model
     ),
+    "airllm": lambda model=None: AirLLMDriver(
+        model=model or settings.airllm_model,
+        compression=settings.airllm_compression,
+    ),
 }
 
 
@@ -115,6 +120,7 @@ __all__ = [
     "GroqDriver",
     "OpenRouterDriver",
     "GrokDriver",
+    "AirLLMDriver",
     "get_driver",
     "get_driver_for_model",
 ]

prompture-0.0.33.dev1/prompture/drivers/airllm_driver.py

@@ -0,0 +1,116 @@
+import logging
+from ..driver import Driver
+from typing import Any, Dict, Optional
+
+logger = logging.getLogger(__name__)
+
+
+class AirLLMDriver(Driver):
+    """Driver for AirLLM — run large models (70B+) on consumer GPUs via
+    layer-by-layer memory management.
+
+    The ``airllm`` package is a lazy dependency: it is imported on first
+    ``generate()`` call so the rest of Prompture works without it installed.
+    """
+
+    MODEL_PRICING = {
+        "default": {"prompt": 0.0, "completion": 0.0}
+    }
+
+    def __init__(self, model: str = "meta-llama/Llama-2-7b-hf",
+                 compression: Optional[str] = None):
+        """
+        Args:
+            model: HuggingFace repo ID (e.g. ``"meta-llama/Llama-2-70b-hf"``).
+            compression: Optional quantization mode — ``"4bit"`` or ``"8bit"``.
+        """
+        self.model = model
+        self.compression = compression
+        self.options: Dict[str, Any] = {}
+        self._llm = None
+        self._tokenizer = None
+
+    # ------------------------------------------------------------------
+    # Lazy model loading
+    # ------------------------------------------------------------------
+    def _ensure_loaded(self):
+        """Load the AirLLM model and tokenizer on first use."""
+        if self._llm is not None:
+            return
+
+        try:
+            from airllm import AutoModel
+        except ImportError:
+            raise ImportError(
+                "The 'airllm' package is required for the AirLLM driver. "
+                "Install it with: pip install prompture[airllm]"
+            )
+
+        try:
+            from transformers import AutoTokenizer
+        except ImportError:
+            raise ImportError(
+                "The 'transformers' package is required for the AirLLM driver. "
+                "Install it with: pip install transformers"
+            )
+
+        logger.info(f"Loading AirLLM model: {self.model} "
+                     f"(compression={self.compression})")
+
+        load_kwargs: Dict[str, Any] = {}
+        if self.compression:
+            load_kwargs["compression"] = self.compression
+
+        self._llm = AutoModel.from_pretrained(self.model, **load_kwargs)
+        self._tokenizer = AutoTokenizer.from_pretrained(self.model)
+        logger.info("AirLLM model loaded successfully")
+
+    # ------------------------------------------------------------------
+    # Driver interface
+    # ------------------------------------------------------------------
+    def generate(self, prompt: str, options: Dict[str, Any] = None) -> Dict[str, Any]:
+        self._ensure_loaded()
+
+        merged_options = self.options.copy()
+        if options:
+            merged_options.update(options)
+
+        max_new_tokens = merged_options.get("max_new_tokens", 256)
+
+        # Tokenize
+        input_ids = self._tokenizer(
+            prompt, return_tensors="pt"
+        ).input_ids
+
+        prompt_tokens = input_ids.shape[1]
+
+        logger.debug(f"AirLLM generating with max_new_tokens={max_new_tokens}, "
+                      f"prompt_tokens={prompt_tokens}")
+
+        # Generate
+        output_ids = self._llm.generate(
+            input_ids,
+            max_new_tokens=max_new_tokens,
+        )
+
+        # Decode only the newly generated tokens (strip the prompt prefix)
+        new_tokens = output_ids[0, prompt_tokens:]
+        completion_tokens = len(new_tokens)
+        text = self._tokenizer.decode(new_tokens, skip_special_tokens=True)
+
+        total_tokens = prompt_tokens + completion_tokens
+
+        meta = {
+            "prompt_tokens": prompt_tokens,
+            "completion_tokens": completion_tokens,
+            "total_tokens": total_tokens,
+            "cost": 0.0,
+            "raw_response": {
+                "model": self.model,
+                "compression": self.compression,
+                "max_new_tokens": max_new_tokens,
+            },
+            "model_name": self.model,
+        }
+
+        return {"text": text, "meta": meta}

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/prompture/settings.py

@@ -48,6 +48,10 @@ class Settings(BaseSettings):
     grok_api_key: Optional[str] = None
     grok_model: str = "grok-4-fast-reasoning"
 
+    # AirLLM
+    airllm_model: str = "meta-llama/Llama-2-7b-hf"
+    airllm_compression: Optional[str] = None  # "4bit" or "8bit"
+
     model_config = SettingsConfigDict(
         env_file=".env",
         extra="ignore",

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/prompture.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 0.0.32.dev1
+Version: 0.0.33.dev1
 Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
 Home-page: https://github.com/jhd3197/prompture
 Author: Juan Denis
@@ -29,6 +29,8 @@ Requires-Dist: tukuy>=0.0.6
 Requires-Dist: pyyaml>=6.0
 Provides-Extra: test
 Requires-Dist: pytest>=7.0; extra == "test"
+Provides-Extra: airllm
+Requires-Dist: airllm>=2.8.0; extra == "airllm"
 Dynamic: author
 Dynamic: author-email
 Dynamic: classifier

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/prompture.egg-info/SOURCES.txt

@@ -1,4 +1,5 @@
 .env.copy
+CLAUDE.md
 LICENSE
 MANIFEST.in
 README.md
@@ -55,6 +56,7 @@ prompture.egg-info/entry_points.txt
 prompture.egg-info/requires.txt
 prompture.egg-info/top_level.txt
 prompture/drivers/__init__.py
+prompture/drivers/airllm_driver.py
 prompture/drivers/azure_driver.py
 prompture/drivers/claude_driver.py
 prompture/drivers/google_driver.py

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/prompture.egg-info/requires.txt

@@ -15,5 +15,8 @@ python-dateutil>=2.9.0
 tukuy>=0.0.6
 pyyaml>=6.0
 
+[airllm]
+airllm>=2.8.0
+
 [test]
 pytest>=7.0

{prompture-0.0.32.dev1 → prompture-0.0.33.dev1}/setup.py

@@ -47,5 +47,6 @@ setup(
     },
     extras_require={
         "test": ["pytest>=7.0"],
+        "airllm": ["airllm>=2.8.0"],
     },
 )