prompture 1.1.4.dev2__tar.gz → 1.1.5.dev1__tar.gz

{prompture-1.1.4.dev2 → prompture-1.1.5.dev1}/PKG-INFO

@@ -1,13 +1,13 @@
 Metadata-Version: 2.4
 Name: prompture
-Version: 1.1.4.dev2
+Version: 1.1.5.dev1
 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
+Requires-Python: >=3.10
 Description-Content-Type: text/markdown
 License-File: LICENSE
 Requires-Dist: click>=8.0
@@ -132,6 +132,18 @@ person = extract_with_model(Person, "Maria is 32, a developer in NYC.", model_na
 print(person.name)  # Maria
 ```
 
+> **First time?** Pick a provider and install its extra. The core package above
+> is just the orchestration layer — provider SDKs are opt-in.
+>
+> | Use `provider/...` | Install | Auth env var |
+> |---|---|---|
+> | `openai/gpt-4`, `openai/gpt-4o-mini`, … | `pip install "prompture[openai]"` | `OPENAI_API_KEY` |
+> | `claude/claude-sonnet-4-6`, … | `pip install "prompture[anthropic]"` | `CLAUDE_API_KEY` |
+> | `google/gemini-1.5-pro`, … | `pip install "prompture[google]"` | `GOOGLE_API_KEY` |
+> | `groq/llama-3.1-8b-instant`, … | `pip install "prompture[groq]"` | `GROQ_API_KEY` |
+> | `ollama/llama3.1:8b`, … (local) | no extra needed | — (set `OLLAMA_HOST` if non-default) |
+> | everything in one go | `pip install "prompture[all]"` | provider-specific |
+
 ## Key Features
 
 **Structured extraction**
@@ -951,6 +963,21 @@ print(result["usage"])        # token counts and cost
 
 Prompture picks how to obtain structured JSON based on each model's capabilities. The cascade is `provider_native` (built-in JSON mode / schema enforcement) → `tool_call` (encode the schema as a function definition and read it back from the tool call) → `prompted_repair` (prompt for JSON, repair malformed output via AI cleanup). Pass `strategy="auto"` (default) to let Prompture select per model, or pin a specific strategy via the `StructuredOutputStrategy` enum or its string value. The strategy used is recorded in the response so you can see which path each call took.
 
+### Constrained Decoding (vLLM / LMStudio / OpenRouter)
+
+For any OpenAI-compatible driver — `OpenAICompatibleDriver`, `OpenRouterDriver`, `LMStudioDriver` (sync + async) — set `options={"guided_decoding": True}` to also ship vLLM-style `guided_json` fields alongside the standard `response_format`. That unlocks logit-level FSM-constrained sampling (100% schema validity at sample time) on backends that support it. Pin a specific backend with `"outlines"`, `"xgrammar"`, or `"lm-format-enforcer"`:
+
+```python
+result = extract_with_model(
+    Person,
+    "Maria is 32, a developer in NYC.",
+    model_name="openai_compatible/local-vllm",
+    options={"guided_decoding": "xgrammar"},   # fast lattice FSM
+)
+```
+
+Unknown servers ignore the extra fields, so it's safe to leave on. An `options={"extra_body": {...}}` escape hatch mirrors the OpenAI SDK so you can also pass `min_p`, `repetition_penalty`, OpenRouter provider preferences, etc. See `examples/constrained_decoding_example.py`.
+
 ### Multi-Model Fallback
 
 Try a list of models in priority order, with full per-attempt accounting — every model tried (success, failure, or skipped) is recorded with its cost, tokens, duration, capabilities, and strategy. The first success wins; if all fail, an optional `fallback` Pydantic instance is returned instead of raising.
@@ -1067,8 +1094,8 @@ 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
+response = conv.ask("What is the capital of France?")
+follow_up = conv.ask("What about Germany?")  # retains context
 ```
 
 ### Tool Use
@@ -1377,6 +1404,37 @@ if doc.found:
 
 Both helpers return plain dataclasses with no I/O of their own.  See `examples/assistant_example.py` for the assistant + review-loop + extractor flow end-to-end.
 
+### Prompt Caching (Claude)
+
+Anthropic prompt caching cuts input-token cost on cached prefixes to ~10% of
+the normal rate. Prompture turns it on by default for `ClaudeDriver` and
+`AsyncClaudeDriver` whenever the system prompt or tools bundle is large
+enough to benefit (≥4000 chars, roughly 1024 tokens — Anthropic's minimum
+cacheable block).
+
+```python
+from prompture import Conversation
+
+# Caching is automatic. The first call writes the cache (~1.25x cost on the
+# cached portion); subsequent calls within 5 minutes hit it (~0.1x cost).
+conv = Conversation(model_name="claude/claude-sonnet-4-6", system_prompt=LONG_SYSTEM_PROMPT)
+conv.ask("First question")   # cache_creation_input_tokens > 0
+conv.ask("Second question")  # cache_read_input_tokens > 0
+```
+
+To inspect cache activity, read `cached_prompt_tokens` and
+`cache_creation_tokens` from the response meta. To disable caching for a
+specific call pass `options={"cache_prompt": False}`.
+
+Tips:
+- Put stable content (persona, tools description, JSON schema) at the
+  **start** of the system prompt; put per-call variables (user query,
+  retrieved RAG context) in the message stream so they don't bust the cache.
+- Avoid `{{iteration}}` or other per-turn variables in Persona templates —
+  they rotate the cache key every turn.
+- Block size below ~1024 tokens is silently dropped by Anthropic; below
+  the threshold Prompture skips the `cache_control` marker to avoid noise.
+
 ### Cost Pre-flight
 
 Forecast the cost of a call **before** making it.  Accepts either text
@@ -1729,6 +1787,13 @@ request body are forwarded to the driver as schemas; if the model
 returns `tool_calls`, they appear in the response shape so the
 client can execute locally.
 
+> **Single-worker constraint:** the server keeps conversations and
+> rate-limit buckets in **per-process memory**. Run with
+> `uvicorn --workers 1` (the default) — multi-worker deployments will
+> partition state across processes, so a `conversation_id` created on
+> one worker can return 404 on another. A shared-state backend (Redis
+> / Postgres) is on the roadmap.
+
 Selected flags:
 
 | Flag | Purpose |

{prompture-1.1.4.dev2 → prompture-1.1.5.dev1}/README.md

@@ -29,6 +29,18 @@ person = extract_with_model(Person, "Maria is 32, a developer in NYC.", model_na
 print(person.name)  # Maria
 ```
 
+> **First time?** Pick a provider and install its extra. The core package above
+> is just the orchestration layer — provider SDKs are opt-in.
+>
+> | Use `provider/...` | Install | Auth env var |
+> |---|---|---|
+> | `openai/gpt-4`, `openai/gpt-4o-mini`, … | `pip install "prompture[openai]"` | `OPENAI_API_KEY` |
+> | `claude/claude-sonnet-4-6`, … | `pip install "prompture[anthropic]"` | `CLAUDE_API_KEY` |
+> | `google/gemini-1.5-pro`, … | `pip install "prompture[google]"` | `GOOGLE_API_KEY` |
+> | `groq/llama-3.1-8b-instant`, … | `pip install "prompture[groq]"` | `GROQ_API_KEY` |
+> | `ollama/llama3.1:8b`, … (local) | no extra needed | — (set `OLLAMA_HOST` if non-default) |
+> | everything in one go | `pip install "prompture[all]"` | provider-specific |
+
 ## Key Features
 
 **Structured extraction**
@@ -848,6 +860,21 @@ print(result["usage"])        # token counts and cost
 
 Prompture picks how to obtain structured JSON based on each model's capabilities. The cascade is `provider_native` (built-in JSON mode / schema enforcement) → `tool_call` (encode the schema as a function definition and read it back from the tool call) → `prompted_repair` (prompt for JSON, repair malformed output via AI cleanup). Pass `strategy="auto"` (default) to let Prompture select per model, or pin a specific strategy via the `StructuredOutputStrategy` enum or its string value. The strategy used is recorded in the response so you can see which path each call took.
 
+### Constrained Decoding (vLLM / LMStudio / OpenRouter)
+
+For any OpenAI-compatible driver — `OpenAICompatibleDriver`, `OpenRouterDriver`, `LMStudioDriver` (sync + async) — set `options={"guided_decoding": True}` to also ship vLLM-style `guided_json` fields alongside the standard `response_format`. That unlocks logit-level FSM-constrained sampling (100% schema validity at sample time) on backends that support it. Pin a specific backend with `"outlines"`, `"xgrammar"`, or `"lm-format-enforcer"`:
+
+```python
+result = extract_with_model(
+    Person,
+    "Maria is 32, a developer in NYC.",
+    model_name="openai_compatible/local-vllm",
+    options={"guided_decoding": "xgrammar"},   # fast lattice FSM
+)
+```
+
+Unknown servers ignore the extra fields, so it's safe to leave on. An `options={"extra_body": {...}}` escape hatch mirrors the OpenAI SDK so you can also pass `min_p`, `repetition_penalty`, OpenRouter provider preferences, etc. See `examples/constrained_decoding_example.py`.
+
 ### Multi-Model Fallback
 
 Try a list of models in priority order, with full per-attempt accounting — every model tried (success, failure, or skipped) is recorded with its cost, tokens, duration, capabilities, and strategy. The first success wins; if all fail, an optional `fallback` Pydantic instance is returned instead of raising.
@@ -964,8 +991,8 @@ 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
+response = conv.ask("What is the capital of France?")
+follow_up = conv.ask("What about Germany?")  # retains context
 ```
 
 ### Tool Use
@@ -1274,6 +1301,37 @@ if doc.found:
 
 Both helpers return plain dataclasses with no I/O of their own.  See `examples/assistant_example.py` for the assistant + review-loop + extractor flow end-to-end.
 
+### Prompt Caching (Claude)
+
+Anthropic prompt caching cuts input-token cost on cached prefixes to ~10% of
+the normal rate. Prompture turns it on by default for `ClaudeDriver` and
+`AsyncClaudeDriver` whenever the system prompt or tools bundle is large
+enough to benefit (≥4000 chars, roughly 1024 tokens — Anthropic's minimum
+cacheable block).
+
+```python
+from prompture import Conversation
+
+# Caching is automatic. The first call writes the cache (~1.25x cost on the
+# cached portion); subsequent calls within 5 minutes hit it (~0.1x cost).
+conv = Conversation(model_name="claude/claude-sonnet-4-6", system_prompt=LONG_SYSTEM_PROMPT)
+conv.ask("First question")   # cache_creation_input_tokens > 0
+conv.ask("Second question")  # cache_read_input_tokens > 0
+```
+
+To inspect cache activity, read `cached_prompt_tokens` and
+`cache_creation_tokens` from the response meta. To disable caching for a
+specific call pass `options={"cache_prompt": False}`.
+
+Tips:
+- Put stable content (persona, tools description, JSON schema) at the
+  **start** of the system prompt; put per-call variables (user query,
+  retrieved RAG context) in the message stream so they don't bust the cache.
+- Avoid `{{iteration}}` or other per-turn variables in Persona templates —
+  they rotate the cache key every turn.
+- Block size below ~1024 tokens is silently dropped by Anthropic; below
+  the threshold Prompture skips the `cache_control` marker to avoid noise.
+
 ### Cost Pre-flight
 
 Forecast the cost of a call **before** making it.  Accepts either text
@@ -1626,6 +1684,13 @@ request body are forwarded to the driver as schemas; if the model
 returns `tool_calls`, they appear in the response shape so the
 client can execute locally.
 
+> **Single-worker constraint:** the server keeps conversations and
+> rate-limit buckets in **per-process memory**. Run with
+> `uvicorn --workers 1` (the default) — multi-worker deployments will
+> partition state across processes, so a `conversation_id` created on
+> one worker can return 404 on another. A shared-state backend (Redis
+> / Postgres) is on the roadmap.
+
 Selected flags:
 
 | Flag | Purpose |

{prompture-1.1.4.dev2 → prompture-1.1.5.dev1}/dev.ps1

@@ -47,6 +47,16 @@ function Invoke-AllChecks {
         Write-Host "fixed $fixed files" -ForegroundColor Yellow
     }
 
+    # --- bandit security scan (matches .github/workflows/security.yml) ---
+    Write-Host "  bandit          " -ForegroundColor Cyan -NoNewline
+    $banditOut = & bandit -q -r $pyPath -c "$Root\pyproject.toml" 2>&1
+    if ($LASTEXITCODE -eq 0) {
+        Write-Host "ok" -ForegroundColor Green
+    } else {
+        Write-Host "fail" -ForegroundColor Red
+        $banditOut | Where-Object { $_ -match ">> Issue|Severity|Location" } | ForEach-Object { Write-Host "    $_" -ForegroundColor DarkGray }
+    }
+
     # --- mypy type check ---
     Write-Host "  mypy            " -ForegroundColor Cyan -NoNewline
     $out = & mypy $pyPath 2>&1

{prompture-1.1.4.dev2 → prompture-1.1.5.dev1}/prompture/__init__.py

@@ -9,7 +9,27 @@ try:
 except ImportError:  # tukuy not installed
     TukuyLLMBackend = None  # type: ignore[assignment,misc]
     create_tukuy_backend = None  # type: ignore[assignment]
+from . import eval as eval
 from . import plugins, rag
+from .checkpoints import (
+    Checkpoint,
+    CheckpointManager,
+    CheckpointStore,
+    FileCheckpointStore,
+    InMemoryCheckpointStore,
+    RunStatus,
+    SQLiteCheckpointStore,
+    restore_conversation,
+    snapshot_conversation,
+)
+from .citations import (
+    CITATION_INSTRUCTION,
+    Citation,
+    CitationTracker,
+    CitedAnswer,
+    Source,
+    extract_citations,
+)
 from .cli import *
 from .dataset import (
     ChatTurn,
@@ -22,6 +42,17 @@ from .dataset import (
     to_sharegpt,
 )
 from .drivers import *
+from .eval import (
+    EvalError,
+    FaithfulnessEvaluator,
+    FaithfulnessResult,
+    JudgeResult,
+    LLMJudge,
+    PairwiseJudge,
+    PairwiseResult,
+    SelfConsistencyEvaluator,
+    SelfConsistencyResult,
+)
 from .exceptions import (
     BudgetExceededError,
     ConfigurationError,
@@ -35,6 +66,17 @@ from .groups import *
 from .infra import *
 from .ingestion import *
 from .integrations import *
+from .kg import (
+    Entity,
+    EntityStore,
+    InMemoryEntityStore,
+    KnowledgeGraph,
+    Mention,
+    Relation,
+    SQLiteEntityStore,
+    extract_entities,
+    extract_relations,
+)
 from .media import *
 from .persistence import *
 from .pipeline import *
@@ -57,6 +99,34 @@ from .security import (
     is_prompt_injection,
     redact_pii,
 )
+from .session_memory import (
+    InMemorySessionStore,
+    MemoryFact,
+    MemoryKind,
+    SessionMemory,
+    SessionMemoryStore,
+    SQLiteSessionStore,
+    Summarizer,
+)
+from .swarm import (
+    AllScheduler,
+    CallableScheduler,
+    Environment,
+    Event,
+    EventKind,
+    InMemoryStore,
+    Memory,
+    MemoryStore,
+    PriorityScheduler,
+    RoundRobinScheduler,
+    SampleScheduler,
+    Scheduler,
+    Swarm,
+    SwarmAgent,
+    SwarmCallbacks,
+    SwarmResult,
+    SwarmStep,
+)
 from .tools import (
     PythonSandboxTool,
     SearchResult,

prompture-1.1.5.dev1/prompture/_internal/__init__.py

@@ -0,0 +1,5 @@
+"""Private internal helpers — NOT part of the public API.
+
+Anything in :mod:`prompture._internal` may change without a deprecation
+window. Do not import from here in downstream code.
+"""

prompture-1.1.5.dev1/prompture/_internal/json_encoder.py

@@ -0,0 +1,118 @@
+"""Shared JSON encoder for Prompture.
+
+Replaces the ``json.dumps(..., default=str)`` pattern that was duplicated
+across ~15 call sites. The previous pattern coerced *everything* unknown
+to a string, including silently stringifying objects that should have
+serialized into structured forms (Pydantic models, sets, bytes…). This
+encoder handles the common Python types Prompture actually emits.
+
+Usage::
+
+    from prompture._internal.json_encoder import dumps, PromptureJSONEncoder
+
+    text = dumps(payload)                      # one-shot
+    text = json.dumps(payload, cls=PromptureJSONEncoder)  # in existing call
+
+Types handled (in order of precedence):
+
+* ``datetime`` / ``date`` / ``time``  → ISO 8601 string
+* ``timedelta``                       → total seconds (float)
+* ``Decimal``                         → str (preserves precision)
+* ``UUID``                            → str
+* ``Enum``                            → ``.value``
+* ``pathlib.PurePath``                → ``str(path)``
+* ``pydantic.BaseModel``              → ``model.model_dump(mode="json")``
+* ``set`` / ``frozenset``             → sorted list (deterministic output)
+* ``bytes`` / ``bytearray``           → ``ascii`` if printable, else ``base64``
+* anything with ``__dict__``          → its ``__dict__``
+* fallback                            → ``str(obj)`` (matches old behaviour)
+"""
+
+from __future__ import annotations
+
+import base64
+import json
+from datetime import date, datetime, time, timedelta
+from decimal import Decimal
+from enum import Enum
+from pathlib import PurePath
+from typing import Any
+from uuid import UUID
+
+
+def _encode_bytes(raw: bytes | bytearray) -> str:
+    """Round-trip bytes as ASCII when printable, otherwise base64."""
+    blob = bytes(raw)
+    try:
+        decoded = blob.decode("ascii")
+    except UnicodeDecodeError:
+        return base64.b64encode(blob).decode("ascii")
+    if decoded.isprintable():
+        return decoded
+    return base64.b64encode(blob).decode("ascii")
+
+
+class PromptureJSONEncoder(json.JSONEncoder):
+    """JSON encoder that knows how to serialise Prompture's common types.
+
+    Falls back to ``str(obj)`` for anything unrecognised so this is a
+    drop-in replacement for ``json.dumps(..., default=str)``.
+    """
+
+    def default(self, o: Any) -> Any:
+        # datetime/date/time first because datetime is a subclass of date
+        if isinstance(o, datetime):
+            return o.isoformat()
+        if isinstance(o, date):
+            return o.isoformat()
+        if isinstance(o, time):
+            return o.isoformat()
+        if isinstance(o, timedelta):
+            return o.total_seconds()
+        if isinstance(o, Decimal):
+            return str(o)
+        if isinstance(o, UUID):
+            return str(o)
+        if isinstance(o, Enum):
+            return o.value
+        if isinstance(o, PurePath):
+            return str(o)
+        if isinstance(o, (set, frozenset)):
+            try:
+                return sorted(o)
+            except TypeError:
+                # Items not comparable (e.g. raw Enum members). Fall back to a
+                # str()-keyed sort so output stays deterministic — important for
+                # cache-key stability.
+                return sorted(o, key=str)
+        if isinstance(o, (bytes, bytearray)):
+            return _encode_bytes(o)
+
+        # Pydantic BaseModel — imported lazily to avoid hard dep at import time.
+        try:
+            from pydantic import BaseModel
+        except ImportError:
+            BaseModel = None  # type: ignore[assignment]
+        if BaseModel is not None and isinstance(o, BaseModel):
+            return o.model_dump(mode="json")
+
+        if hasattr(o, "__dict__"):
+            return o.__dict__
+
+        # Final fallback: stringify. Matches the legacy ``default=str`` behaviour
+        # so this encoder cannot regress callers that depended on it.
+        return str(o)
+
+
+def dumps(obj: Any, **kwargs: Any) -> str:
+    """``json.dumps`` shortcut using :class:`PromptureJSONEncoder`.
+
+    Any keyword args are forwarded to :func:`json.dumps`. Setting ``cls``
+    explicitly will override the default encoder.
+    """
+    kwargs.setdefault("cls", PromptureJSONEncoder)
+    kwargs.setdefault("ensure_ascii", False)
+    return json.dumps(obj, **kwargs)
+
+
+__all__ = ["PromptureJSONEncoder", "dumps"]

{prompture-1.1.4.dev2 → prompture-1.1.5.dev1}/prompture/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '1.1.4.dev2'
-__version_tuple__ = version_tuple = (1, 1, 4, 'dev2')
+__version__ = version = '1.1.5.dev1'
+__version_tuple__ = version_tuple = (1, 1, 5, 'dev1')
 
 __commit_id__ = commit_id = None

{prompture-1.1.4.dev2 → prompture-1.1.5.dev1}/prompture/agents/__init__.py

@@ -1,6 +1,6 @@
 """Agents, conversations, personas, skills, and tool schemas."""
 
-from .agent import Agent, AgentIterator, StreamedAgentResult
+from .agent import Agent, AgentIterator, LiveAgentResult, StreamedAgentResult
 from .assistant import (
     Assistant,
     AssistantResult,
@@ -10,7 +10,7 @@ from .assistant import (
     register_assistant,
     unregister_assistant,
 )
-from .async_agent import AsyncAgent, AsyncAgentIterator, AsyncStreamedAgentResult
+from .async_agent import AsyncAgent, AsyncAgentIterator, AsyncLiveAgentResult, AsyncStreamedAgentResult
 from .async_conversation import AsyncConversation
 from .async_deep_agent import AsyncDeepAgent, create_async_deep_agent
 from .conversation import Conversation
@@ -23,6 +23,18 @@ from .deep_state import (
     SummaryEvent,
     Todo,
 )
+from .live_events import (
+    AssistantTurnStart,
+    LiveEvent,
+    MessageStop,
+    TextDelta,
+    ThinkingDelta,
+    ToolInputDelta,
+    ToolResult,
+    ToolUseStart,
+    ToolUseStop,
+    TurnComplete,
+)
 from .persona import (
     PERSONAS,
     Persona,
@@ -90,10 +102,12 @@ __all__ = [
     "ApprovalRequired",
     "Assistant",
     "AssistantResult",
+    "AssistantTurnStart",
     "AsyncAgent",
     "AsyncAgentIterator",
     "AsyncConversation",
     "AsyncDeepAgent",
+    "AsyncLiveAgentResult",
     "AsyncReviewLoop",
     "AsyncStreamedAgentResult",
     "Conversation",
@@ -101,6 +115,9 @@ __all__ = [
     "DeepAgentResult",
     "DeepAgentState",
     "GuardrailError",
+    "LiveAgentResult",
+    "LiveEvent",
+    "MessageStop",
     "ModelRetry",
     "Persona",
     "ReviewLoopEvent",
@@ -118,9 +135,16 @@ __all__ = [
     "SubAgentCallRecord",
     "SubAgentSpec",
     "SummaryEvent",
+    "TextDelta",
+    "ThinkingDelta",
     "Todo",
     "ToolDefinition",
+    "ToolInputDelta",
     "ToolRegistry",
+    "ToolResult",
+    "ToolUseStart",
+    "ToolUseStop",
+    "TurnComplete",
     "clear_assistant_registry",
     "clear_persona_registry",
     "clear_skill_registry",