prompture 0.0.29.dev8__py3-none-any.whl → 0.0.38.dev2__py3-none-any.whl

prompture/tools_schema.py

@@ -0,0 +1,254 @@
+"""Function calling / tool use support for Prompture.
+
+Provides :class:`ToolDefinition` for describing callable tools,
+:class:`ToolRegistry` for managing a collection of tools, and
+:func:`tool_from_function` to auto-generate tool schemas from type hints.
+
+Example::
+
+    from prompture import ToolRegistry
+
+    registry = ToolRegistry()
+
+    @registry.tool
+    def get_weather(city: str, units: str = "celsius") -> str:
+        \"\"\"Get the current weather for a city.\"\"\"
+        return f"Weather in {city}: 22 {units}"
+
+    # Or register explicitly
+    registry.register(get_weather)
+"""
+
+from __future__ import annotations
+
+import inspect
+import logging
+from dataclasses import dataclass, field
+from typing import Any, Callable, get_type_hints
+
+logger = logging.getLogger("prompture.tools_schema")
+
+# Mapping from Python types to JSON Schema types
+_TYPE_MAP: dict[type, str] = {
+    str: "string",
+    int: "integer",
+    float: "number",
+    bool: "boolean",
+    list: "array",
+    dict: "object",
+}
+
+
+def _python_type_to_json_schema(annotation: Any) -> dict[str, Any]:
+    """Convert a Python type annotation to a JSON Schema snippet."""
+    if annotation is inspect.Parameter.empty or annotation is None:
+        return {"type": "string"}
+
+    # Handle Optional[X] (Union[X, None])
+    origin = getattr(annotation, "__origin__", None)
+    args = getattr(annotation, "__args__", ())
+
+    if origin is type(None):
+        return {"type": "string"}
+
+    # Union types (Optional)
+    if origin is not None and hasattr(origin, "__name__") and origin.__name__ == "Union":
+        non_none = [a for a in args if a is not type(None)]
+        if len(non_none) == 1:
+            return _python_type_to_json_schema(non_none[0])
+
+    # list[X]
+    if origin is list and args:
+        return {"type": "array", "items": _python_type_to_json_schema(args[0])}
+
+    # dict[str, X]
+    if origin is dict:
+        return {"type": "object"}
+
+    # Simple types
+    json_type = _TYPE_MAP.get(annotation, "string")
+    return {"type": json_type}
+
+
+@dataclass
+class ToolDefinition:
+    """Describes a single callable tool the LLM can invoke.
+
+    Attributes:
+        name: Unique tool identifier.
+        description: Human-readable description shown to the LLM.
+        parameters: JSON Schema describing the function parameters.
+        function: The Python callable to execute.
+    """
+
+    name: str
+    description: str
+    parameters: dict[str, Any]
+    function: Callable[..., Any]
+
+    # ------------------------------------------------------------------
+    # Serialisation helpers
+    # ------------------------------------------------------------------
+
+    def to_openai_format(self) -> dict[str, Any]:
+        """Serialise to OpenAI ``tools`` array element format."""
+        return {
+            "type": "function",
+            "function": {
+                "name": self.name,
+                "description": self.description,
+                "parameters": self.parameters,
+            },
+        }
+
+    def to_anthropic_format(self) -> dict[str, Any]:
+        """Serialise to Anthropic ``tools`` array element format."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": self.parameters,
+        }
+
+
+def tool_from_function(fn: Callable[..., Any], *, name: str | None = None, description: str | None = None) -> ToolDefinition:
+    """Build a :class:`ToolDefinition` by inspecting *fn*'s signature and docstring.
+
+    Parameters:
+        fn: The callable to wrap.
+        name: Override the tool name (defaults to ``fn.__name__``).
+        description: Override the description (defaults to the first line of the docstring).
+    """
+    tool_name = name or fn.__name__
+    tool_desc = description or (inspect.getdoc(fn) or "").split("\n")[0] or f"Call {tool_name}"
+
+    sig = inspect.signature(fn)
+    try:
+        hints = get_type_hints(fn)
+    except Exception:
+        hints = {}
+
+    properties: dict[str, Any] = {}
+    required: list[str] = []
+
+    for param_name, param in sig.parameters.items():
+        if param_name == "self":
+            continue
+        annotation = hints.get(param_name, param.annotation)
+        prop = _python_type_to_json_schema(annotation)
+
+        # Use parameter name as description fallback
+        prop.setdefault("description", f"Parameter: {param_name}")
+
+        properties[param_name] = prop
+
+        if param.default is inspect.Parameter.empty:
+            required.append(param_name)
+
+    parameters: dict[str, Any] = {
+        "type": "object",
+        "properties": properties,
+    }
+    if required:
+        parameters["required"] = required
+
+    return ToolDefinition(
+        name=tool_name,
+        description=tool_desc,
+        parameters=parameters,
+        function=fn,
+    )
+
+
+@dataclass
+class ToolRegistry:
+    """A collection of :class:`ToolDefinition` instances.
+
+    Supports decorator-based and explicit registration::
+
+        registry = ToolRegistry()
+
+        @registry.tool
+        def my_func(x: int) -> str:
+            ...
+
+        registry.register(another_func)
+    """
+
+    _tools: dict[str, ToolDefinition] = field(default_factory=dict)
+
+    # ------------------------------------------------------------------
+    # Registration
+    # ------------------------------------------------------------------
+
+    def register(
+        self,
+        fn: Callable[..., Any],
+        *,
+        name: str | None = None,
+        description: str | None = None,
+    ) -> ToolDefinition:
+        """Register *fn* as a tool and return the :class:`ToolDefinition`."""
+        td = tool_from_function(fn, name=name, description=description)
+        self._tools[td.name] = td
+        return td
+
+    def tool(self, fn: Callable[..., Any]) -> Callable[..., Any]:
+        """Decorator to register a function as a tool.
+
+        Returns the original function unchanged so it remains callable.
+        """
+        self.register(fn)
+        return fn
+
+    def add(self, tool_def: ToolDefinition) -> None:
+        """Add a pre-built :class:`ToolDefinition`."""
+        self._tools[tool_def.name] = tool_def
+
+    # ------------------------------------------------------------------
+    # Lookup
+    # ------------------------------------------------------------------
+
+    def get(self, name: str) -> ToolDefinition | None:
+        return self._tools.get(name)
+
+    def __contains__(self, name: str) -> bool:
+        return name in self._tools
+
+    def __len__(self) -> int:
+        return len(self._tools)
+
+    def __bool__(self) -> bool:
+        return bool(self._tools)
+
+    @property
+    def names(self) -> list[str]:
+        return list(self._tools.keys())
+
+    @property
+    def definitions(self) -> list[ToolDefinition]:
+        return list(self._tools.values())
+
+    # ------------------------------------------------------------------
+    # Serialisation
+    # ------------------------------------------------------------------
+
+    def to_openai_format(self) -> list[dict[str, Any]]:
+        return [td.to_openai_format() for td in self._tools.values()]
+
+    def to_anthropic_format(self) -> list[dict[str, Any]]:
+        return [td.to_anthropic_format() for td in self._tools.values()]
+
+    # ------------------------------------------------------------------
+    # Execution
+    # ------------------------------------------------------------------
+
+    def execute(self, name: str, arguments: dict[str, Any]) -> Any:
+        """Execute a registered tool by name with the given arguments.
+
+        Raises:
+            KeyError: If no tool with *name* is registered.
+        """
+        td = self._tools.get(name)
+        if td is None:
+            raise KeyError(f"Tool not registered: {name!r}")
+        return td.function(**arguments)

prompture/validator.py

@@ -1,5 +1,5 @@
 import json
-from typing import Any, Dict
+from typing import Any
 
 try:
     import jsonschema
@@ -7,7 +7,7 @@ except Exception:
     jsonschema = None
 
 
-def validate_against_schema(instance_json: str, schema: Dict[str,Any]) -> Dict[str,Any]:
+def validate_against_schema(instance_json: str, schema: dict[str, Any]) -> dict[str, Any]:
     """Valida el JSON (string) contra un JSON Schema.
     Devuelve dict con ok: bool y detalles.
     """
@@ -28,4 +28,4 @@ def validate_against_schema(instance_json: str, schema: Dict[str,Any]) -> Dict[s
         jsonschema.validate(instance=data, schema=schema)
         return {"ok": True, "data": data}
     except jsonschema.ValidationError as e:
-        return {"ok": False, "error": str(e), "data": data}
+        return {"ok": False, "error": str(e), "data": data}

prompture-0.0.38.dev2.dist-info/METADATA

@@ -0,0 +1,369 @@
+Metadata-Version: 2.4
+Name: prompture
+Version: 0.0.38.dev2
+Summary: Ask LLMs to return structured JSON and run cross-model tests. API-first.
+Author-email: Juan Denis <juan@vene.co>
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/jhd3197/prompture
+Classifier: Programming Language :: Python :: 3
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: anthropic>=0.8.0
+Requires-Dist: click>=8.0
+Requires-Dist: google-generativeai>=0.3.0
+Requires-Dist: groq>=0.4.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: pandas>=1.3.0
+Requires-Dist: pydantic>=1.10
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-dotenv>=0.19.0
+Requires-Dist: python-toon>=0.1.0
+Requires-Dist: requests>=2.28
+Requires-Dist: python-dateutil>=2.9.0
+Requires-Dist: tukuy>=0.0.6
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: test
+Requires-Dist: pytest>=7.0; extra == "test"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "test"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.23.0; extra == "dev"
+Requires-Dist: ruff>=0.8.0; extra == "dev"
+Provides-Extra: airllm
+Requires-Dist: airllm>=2.8.0; extra == "airllm"
+Provides-Extra: redis
+Requires-Dist: redis>=4.0; extra == "redis"
+Provides-Extra: serve
+Requires-Dist: fastapi>=0.100; extra == "serve"
+Requires-Dist: uvicorn[standard]>=0.20; extra == "serve"
+Requires-Dist: sse-starlette>=1.6; extra == "serve"
+Provides-Extra: scaffold
+Requires-Dist: jinja2>=3.0; extra == "scaffold"
+Dynamic: license-file
+
+<p align="center">
+  <h1 align="center">Prompture</h1>
+  <p align="center">Structured JSON extraction from any LLM. Schema-enforced, Pydantic-native, multi-provider.</p>
+</p>
+
+<p align="center">
+  <a href="https://pypi.org/project/prompture/"><img src="https://badge.fury.io/py/prompture.svg" alt="PyPI version"></a>
+  <a href="https://pypi.org/project/prompture/"><img src="https://img.shields.io/pypi/pyversions/prompture.svg" alt="Python versions"></a>
+  <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-blue.svg" alt="License: MIT"></a>
+  <a href="https://pepy.tech/project/prompture"><img src="https://static.pepy.tech/badge/prompture" alt="Downloads"></a>
+  <a href="https://github.com/jhd3197/prompture"><img src="https://img.shields.io/github/stars/jhd3197/prompture?style=social" alt="GitHub stars"></a>
+</p>
+
+---
+
+**Prompture** is a Python library that turns LLM responses into validated, structured data. Define a schema or Pydantic model, point it at any provider, and get typed output back — with token tracking, cost calculation, and automatic JSON repair built in.
+
+```python
+from pydantic import BaseModel
+from prompture import extract_with_model
+
+class Person(BaseModel):
+    name: str
+    age: int
+    profession: str
+
+person = extract_with_model(Person, "Maria is 32, a developer in NYC.", model_name="openai/gpt-4")
+print(person.name)  # Maria
+```
+
+## Key Features
+
+- **Structured output** — JSON schema enforcement and direct Pydantic model population
+- **12 providers** — OpenAI, Claude, Google, Groq, Grok, Azure, Ollama, LM Studio, OpenRouter, HuggingFace, AirLLM, and generic HTTP
+- **TOON input conversion** — 45-60% token savings when sending structured data via [Token-Oriented Object Notation](https://github.com/jhd3197/python-toon)
+- **Stepwise extraction** — Per-field prompts with smart type coercion (shorthand numbers, multilingual booleans, dates)
+- **Field registry** — 50+ predefined extraction fields with template variables and Pydantic integration
+- **Conversations** — Stateful multi-turn sessions with sync and async support
+- **Tool use** — Function calling and streaming across supported providers
+- **Caching** — Built-in response cache with memory, SQLite, and Redis backends
+- **Plugin system** — Register custom drivers via entry points
+- **Usage tracking** — Token counts and cost calculation on every call
+- **Auto-repair** — Optional second LLM pass to fix malformed JSON
+- **Batch testing** — Spec-driven suites to compare models side by side
+
+## Installation
+
+```bash
+pip install prompture
+```
+
+Optional extras:
+
+```bash
+pip install prompture[redis]     # Redis cache backend
+pip install prompture[serve]     # FastAPI server mode
+pip install prompture[airllm]    # AirLLM local inference
+```
+
+## Configuration
+
+Set API keys for the providers you use. Prompture reads from environment variables or a `.env` file:
+
+```bash
+OPENAI_API_KEY=sk-...
+ANTHROPIC_API_KEY=sk-ant-...
+GOOGLE_API_KEY=...
+GROQ_API_KEY=...
+GROK_API_KEY=...
+OPENROUTER_API_KEY=...
+AZURE_OPENAI_ENDPOINT=...
+AZURE_OPENAI_API_KEY=...
+```
+
+Local providers (Ollama, LM Studio) work out of the box with no keys required.
+
+## Providers
+
+Model strings use `"provider/model"` format. The provider prefix routes to the correct driver automatically.
+
+| Provider | Example Model | Cost |
+|---|---|---|
+| `openai` | `openai/gpt-4` | Automatic |
+| `claude` | `claude/claude-3` | Automatic |
+| `google` | `google/gemini-1.5-pro` | Automatic |
+| `groq` | `groq/llama2-70b-4096` | Automatic |
+| `grok` | `grok/grok-4-fast-reasoning` | Automatic |
+| `azure` | `azure/deployed-name` | Automatic |
+| `openrouter` | `openrouter/anthropic/claude-2` | Automatic |
+| `ollama` | `ollama/llama3.1:8b` | Free (local) |
+| `lmstudio` | `lmstudio/local-model` | Free (local) |
+| `huggingface` | `hf/model-name` | Free (local) |
+| `http` | `http/self-hosted` | Free |
+
+## Usage
+
+### One-Shot Pydantic Extraction
+
+Single LLM call, returns a validated Pydantic instance:
+
+```python
+from typing import List, Optional
+from pydantic import BaseModel
+from prompture import extract_with_model
+
+class Person(BaseModel):
+    name: str
+    age: int
+    profession: str
+    city: str
+    hobbies: List[str]
+    education: Optional[str] = None
+
+person = extract_with_model(
+    Person,
+    "Maria is 32, a software developer in New York. She loves hiking and photography.",
+    model_name="openai/gpt-4"
+)
+print(person.model_dump())
+```
+
+### Stepwise Extraction
+
+One LLM call per field. Higher accuracy, per-field error recovery:
+
+```python
+from prompture import stepwise_extract_with_model
+
+result = stepwise_extract_with_model(
+    Person,
+    "Maria is 32, a software developer in New York. She loves hiking and photography.",
+    model_name="openai/gpt-4"
+)
+print(result["model"].model_dump())
+print(result["usage"])  # per-field and total token usage
+```
+
+| Aspect | `extract_with_model` | `stepwise_extract_with_model` |
+|---|---|---|
+| LLM calls | 1 | N (one per field) |
+| Speed / cost | Faster, cheaper | Slower, higher |
+| Accuracy | Good global coherence | Higher per-field accuracy |
+| Error handling | All-or-nothing | Per-field recovery |
+
+### JSON Schema Extraction
+
+For raw JSON output with full control:
+
+```python
+from prompture import ask_for_json
+
+schema = {
+    "type": "object",
+    "required": ["name", "age"],
+    "properties": {
+        "name": {"type": "string"},
+        "age": {"type": "integer"}
+    }
+}
+
+result = ask_for_json(
+    content_prompt="Extract the person's info from: John is 28 and lives in Miami.",
+    json_schema=schema,
+    model_name="openai/gpt-4"
+)
+print(result["json_object"])  # {"name": "John", "age": 28}
+print(result["usage"])        # token counts and cost
+```
+
+### TOON Input — Token Savings
+
+Analyze structured data with automatic TOON conversion for 45-60% fewer tokens:
+
+```python
+from prompture import extract_from_data
+
+products = [
+    {"id": 1, "name": "Laptop", "price": 999.99, "rating": 4.5},
+    {"id": 2, "name": "Book", "price": 19.99, "rating": 4.2},
+    {"id": 3, "name": "Headphones", "price": 149.99, "rating": 4.7},
+]
+
+result = extract_from_data(
+    data=products,
+    question="What is the average price and highest rated product?",
+    json_schema={
+        "type": "object",
+        "properties": {
+            "average_price": {"type": "number"},
+            "highest_rated": {"type": "string"}
+        }
+    },
+    model_name="openai/gpt-4"
+)
+
+print(result["json_object"])
+# {"average_price": 389.99, "highest_rated": "Headphones"}
+
+print(f"Token savings: {result['token_savings']['percentage_saved']}%")
+```
+
+Works with Pandas DataFrames via `extract_from_pandas()`.
+
+### Field Definitions
+
+Use the built-in field registry for consistent extraction across models:
+
+```python
+from pydantic import BaseModel
+from prompture import field_from_registry, stepwise_extract_with_model
+
+class Person(BaseModel):
+    name: str = field_from_registry("name")
+    age: int = field_from_registry("age")
+    email: str = field_from_registry("email")
+    occupation: str = field_from_registry("occupation")
+
+result = stepwise_extract_with_model(
+    Person,
+    "John Smith, 25, software engineer at TechCorp, john@example.com",
+    model_name="openai/gpt-4"
+)
+```
+
+Register custom fields with template variables:
+
+```python
+from prompture import register_field
+
+register_field("document_date", {
+    "type": "str",
+    "description": "Document creation date",
+    "instructions": "Use {{current_date}} if not specified",
+    "default": "{{current_date}}",
+    "nullable": False
+})
+```
+
+### Conversations
+
+Stateful multi-turn sessions:
+
+```python
+from prompture import Conversation
+
+conv = Conversation(model_name="openai/gpt-4")
+conv.add_message("system", "You are a helpful assistant.")
+response = conv.send("What is the capital of France?")
+follow_up = conv.send("What about Germany?")  # retains context
+```
+
+### Model Discovery
+
+Auto-detect available models from configured providers:
+
+```python
+from prompture import get_available_models
+
+models = get_available_models()
+for model in models:
+    print(model)  # "openai/gpt-4", "ollama/llama3:latest", ...
+```
+
+### Logging and Debugging
+
+```python
+import logging
+from prompture import configure_logging
+
+configure_logging(logging.DEBUG)
+```
+
+### Response Shape
+
+All extraction functions return a consistent structure:
+
+```python
+{
+    "json_string": str,       # raw JSON text
+    "json_object": dict,      # parsed result
+    "usage": {
+        "prompt_tokens": int,
+        "completion_tokens": int,
+        "total_tokens": int,
+        "cost": float,
+        "model_name": str
+    }
+}
+```
+
+## CLI
+
+```bash
+prompture run <spec-file>
+```
+
+Run spec-driven extraction suites for cross-model comparison.
+
+## Development
+
+```bash
+# Install with dev dependencies
+pip install -e ".[test,dev]"
+
+# Run tests
+pytest
+
+# Run integration tests (requires live LLM access)
+pytest --run-integration
+
+# Lint and format
+ruff check .
+ruff format .
+```
+
+## Contributing
+
+PRs welcome. Please add tests for new functionality and examples under `examples/` for new drivers or patterns.
+
+## License
+
+[MIT](https://opensource.org/licenses/MIT)