pgate 0.1.1__py3-none-any.whl

pgate-0.1.1.dist-info/METADATA

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: pgate
+Version: 0.1.1
+Summary: PGate — Prompt ORM for LLM agents. Store, compile, validate and cache prompt contracts locally.
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: jinja2>=3.1
+Requires-Dist: jsonschema>=4.0
+Requires-Dist: loguru>=0.7
+Requires-Dist: mcp>=1.0
+Requires-Dist: pydantic>=2.0
+Requires-Dist: pyyaml>=6.0
+Provides-Extra: crypto
+Requires-Dist: cryptography>=41.0; extra == 'crypto'
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=4.0; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Provides-Extra: litellm
+Requires-Dist: litellm>=1.0; extra == 'litellm'
+Provides-Extra: postgres
+Requires-Dist: psycopg2-binary>=2.9; extra == 'postgres'
+Description-Content-Type: text/markdown
+
+# PGate
+
+**Prompt ORM for LLM agents.** Store, find, compile, validate, and cache prompt contracts — locally, without cloud, without telemetry.
+
+## Install
+
+```bash
+pip install pgate
+```
+
+## Quickstart
+
+```bash
+pgate init
+pgate add --file examples/report_sales.yaml
+pgate compile --interactive
+```
+
+## MCP (Claude Desktop / Cursor)
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "pgate": {
+    "command": "pgate",
+    "args": ["mcp", "--stdio"]
+  }
+}
+```
+
+## Status
+
+v0.1 — in development.

pgate-0.1.1.dist-info/RECORD

@@ -0,0 +1,16 @@
+promptgate/__init__.py,sha256=fa4qeq-zQCkXCJd9jWAE7bvX8NV-jO44hBkzAiSnBvU,251
+promptgate/cli.py,sha256=fBQtcqZXk8rUN7snZgDsO-8xnxvdxS1ma5Cc94YeIcE,12652
+promptgate/compiler.py,sha256=9gDVmYBhlCl6zNTtcFwLZRvz85SLaVyQgaxASViQYA0,7697
+promptgate/file_api.py,sha256=AtE_j0M48euY8O2G_1vkrcJ4xyKwViwLfJrMsbgcLYI,4704
+promptgate/mcp_adapter.py,sha256=QUZ5s7ZH4PDahKPzqFBkRDN0oKq9UGMvKB27n27IsJY,3006
+promptgate/models.py,sha256=AdvcOGW5kLJ46MriLNHfnok5YTOO9RluoAndDfGSsKk,2391
+promptgate/models_registry.py,sha256=baZIgPD_kYw_mwp2FdL-VIc0F6spScZHF16nDTsBdLY,12559
+promptgate/router.py,sha256=7uxQH_04sY8ovyaR3mT6MXFWjuNKo67hrZ_y3VDJdF0,2706
+promptgate/storage.py,sha256=ENtPQNkkbleZSYWKDytk4XqKQa1XRQuB5dzbOZFzPr4,8589
+promptgate/validator.py,sha256=PlwIwXFlQQVgb_AxBhd5Up6n2OUd0xmXVRvzDpvEpO4,3415
+promptgate/backends/__init__.py,sha256=Ep-Z-N3bnmXdkxgZ_xm4GXFRpW_S8lCoxH04n-NNZF8,63
+promptgate/backends/base.py,sha256=vAiRaogukSlfOuDgWJDxtKYP0zNaE6YkiJhtHGfIYm0,515
+pgate-0.1.1.dist-info/METADATA,sha256=Epu8-jZ3U6YI_pMHcSSrKQYP6oC0mQ6CFS0CLjcoygA,1263
+pgate-0.1.1.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+pgate-0.1.1.dist-info/entry_points.txt,sha256=WrYmMfktlR1LioEJxmCiMOXM5-x5k77HqrimDYaQf5U,79
+pgate-0.1.1.dist-info/RECORD,,

pgate-0.1.1.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pgate-0.1.1.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+pgate = promptgate.cli:main
+promptgate = promptgate.cli:main

promptgate/__init__.py

@@ -0,0 +1,6 @@
+from .models import CompiledContract, PromptConfig, ValidationResult
+from .file_api import get_or_compile
+from .router import search
+
+__version__ = "0.1.0"
+__all__ = ["PromptConfig", "CompiledContract", "ValidationResult", "get_or_compile", "search"]

promptgate/backends/__init__.py

@@ -0,0 +1,3 @@
+from .base import StorageBackend
+
+__all__ = ["StorageBackend"]

promptgate/backends/base.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from typing import Protocol, runtime_checkable
+
+from promptgate.models import PromptConfig
+
+
+@runtime_checkable
+class StorageBackend(Protocol):
+    def init(self) -> None: ...
+    def upsert(self, prompt: PromptConfig) -> None: ...
+    def get(self, prompt_id: str) -> PromptConfig | None: ...
+    def delete(self, prompt_id: str) -> bool: ...
+    def list_all(self) -> list[PromptConfig]: ...
+    def search_fts(self, query: str, limit: int = 5) -> list[tuple[str, float]]: ...

promptgate/cli.py

@@ -0,0 +1,365 @@
+"""Click CLI: init, add, search, compile, mcp."""
+from __future__ import annotations
+
+import json
+import sys
+from pathlib import Path
+
+import click
+import yaml
+from loguru import logger
+
+from promptgate.file_api import get_or_compile, purge_stale
+from promptgate.models import PromptConfig
+from promptgate.router import search as pg_search
+from promptgate.storage import SQLiteBackend, _DEFAULT_DB_PATH
+
+
+def _configure_logging(verbose: bool) -> None:
+    logger.remove()
+    level = "DEBUG" if verbose else "INFO"
+    logger.add(sys.stderr, level=level, format="<level>{level}</level> {message}")
+    log_dir = Path("logs")
+    log_dir.mkdir(exist_ok=True)
+    logger.add(
+        log_dir / "app.log",
+        level="DEBUG",
+        rotation="10 MB",
+        retention="7 days",
+        encoding="utf-8",
+    )
+
+
+@click.group()
+@click.option("--verbose", "-v", is_flag=True, default=False, help="Enable debug logging.")
+@click.option(
+    "--db",
+    default=str(_DEFAULT_DB_PATH),
+    show_default=True,
+    help="Path to SQLite database.",
+)
+@click.pass_context
+def main(ctx: click.Context, verbose: bool, db: str) -> None:
+    """PromptGate - Prompt ORM for LLM agents."""
+    ctx.ensure_object(dict)
+    ctx.obj["db"] = db
+    _configure_logging(verbose)
+
+
+@main.command()
+@click.pass_context
+def init(ctx: click.Context) -> None:
+    """Initialize the PromptGate database.
+
+    Creates ~/.promptgate/db.sqlite and FTS5 tables if they don't exist.
+    """
+    backend = SQLiteBackend(ctx.obj["db"])
+    backend.init()
+    click.echo(f"Initialized: {ctx.obj['db']}")
+
+
+@main.command("add")
+@click.option("--file", "-f", "file_path", type=click.Path(exists=True), help="Path to YAML prompt file.")
+@click.option("--url", "-u", help="URL to fetch YAML prompt from.")
+@click.pass_context
+def add_prompt(ctx: click.Context, file_path: str | None, url: str | None) -> None:
+    """Add or update a prompt from a YAML file or URL.
+
+    Examples:
+
+        promptgate add --file examples/report_sales.yaml
+
+        promptgate add --url https://example.com/my_prompt.yaml
+    """
+    if not file_path and not url:
+        raise click.UsageError("Provide --file or --url.")
+
+    raw: str
+    if url:
+        import urllib.request
+        with urllib.request.urlopen(url) as resp:  # noqa: S310
+            raw = resp.read().decode("utf-8")
+    else:
+        raw = Path(file_path).read_text(encoding="utf-8")
+
+    data = yaml.safe_load(raw)
+    prompt = PromptConfig.model_validate(data)
+
+    backend = SQLiteBackend(ctx.obj["db"])
+    backend.init()
+    backend.upsert(prompt)
+    click.echo(f"Added prompt: {prompt.id} ({prompt.name})")
+
+
+@main.command("search")
+@click.argument("query")
+@click.option("--limit", "-n", default=5, show_default=True, help="Max results.")
+@click.pass_context
+def search_cmd(ctx: click.Context, query: str, limit: int) -> None:
+    """Search prompts by full-text relevance.
+
+    Examples:
+
+        promptgate search "sales report"
+    """
+    results = pg_search(query, db_path=ctx.obj["db"], limit=limit)
+    if not results:
+        click.echo("No results.")
+        return
+    for prompt_id, score in results:
+        click.echo(f"  {score:.4f}  {prompt_id}")
+
+
+@main.command("compile")
+@click.argument("prompt_id")
+@click.option("--payload", "-p", default="{}", help="JSON payload string.")
+@click.option("--model", "-m", default=None, help="LLM model ID for model-aware compilation.")
+@click.option("--interactive", "-i", is_flag=True, help="Prompt for each required field interactively.")
+@click.pass_context
+def compile_cmd(ctx: click.Context, prompt_id: str, payload: str, model: str | None, interactive: bool) -> None:
+    """Compile a prompt and print the system_prompt.
+
+    Examples:
+
+        promptgate compile sales_v1 --payload '{"period": "2024-01"}'
+
+        promptgate compile sales_v1 --model gpt-4o --payload '{"period": "2024-01"}'
+
+        promptgate compile sales_v1 --interactive
+    """
+    backend = SQLiteBackend(ctx.obj["db"])
+    backend.init()
+    prompt = backend.get(prompt_id)
+    if prompt is None:
+        raise click.ClickException(f"Prompt '{prompt_id}' not found.")
+
+    data: dict = json.loads(payload)
+
+    if interactive:
+        required = prompt.schema_.get("required", [])
+        props = prompt.schema_.get("properties", {})
+        for field in required:
+            if field not in data:
+                desc = props.get(field, {})
+                hint = desc.get("type", "string")
+                value = click.prompt(f"  {field} ({hint})")
+                data[field] = value
+
+    contract = get_or_compile(prompt_id, data, db_path=ctx.obj["db"], model_id=model)
+    click.echo(contract.system_prompt)
+    if contract.missing_fields:
+        click.echo(f"\n[missing: {', '.join(contract.missing_fields)}]", err=True)
+    if contract.model_hints:
+        h = contract.model_hints
+        rm_tag = {"none": "", "chain_of_thought": f" [CoT:{h.cot_strategy}]", "native": " [think]"}.get(
+            h.reasoning_mode, ""
+        )
+        sys_tag = "" if h.supports_system_prompt else " [no-sys]"
+        logger.debug("Model: {} ({}) ctx={}k{}{}", h.model_id, h.family, h.context_window // 1000, rm_tag, sys_tag)
+
+
+@main.group("models", invoke_without_command=True)
+@click.pass_context
+def models_group(ctx: click.Context) -> None:
+    """Manage LLM model registry.
+
+    Without a subcommand, lists all registered models.
+
+    Examples:
+
+        promptgate models
+
+        promptgate models list --family anthropic
+
+        promptgate models add --id gpt-5 --family openai --ctx 400000 --reasoning native
+
+        promptgate models rm gpt-5
+
+        promptgate models show gpt-4o
+    """
+    if ctx.invoked_subcommand is None:
+        ctx.invoke(models_list)
+
+
+def _print_models_table(rows: list[tuple[str, object]], custom_ids: set[str]) -> None:
+    """Print a formatted table row for each (model_id, ModelCapabilities) pair."""
+    from promptgate.models_registry import ModelCapabilities as MC
+    rm_labels = {"none": "     ", "chain_of_thought": " CoT ", "native": "think"}
+    for name, caps in rows:
+        rm = rm_labels.get(caps.reasoning_mode, "     ")
+        cot = f"/{caps.cot_strategy}" if caps.reasoning_mode == "chain_of_thought" else ""
+        sys_tag = "  " if caps.supports_system_prompt else "NS"
+        json_tag = "J" if caps.json_native else " "
+        ctx_k = caps.context_window // 1000
+        custom_tag = "*" if name in custom_ids else " "
+        click.echo(f"  {custom_tag}[{rm}{cot:<12}] [{sys_tag}][{json_tag}]  ctx={ctx_k:>5}k  {name}")
+
+
+@models_group.command("list")
+@click.option("--family", "-f", default=None, help="Filter by family (openai, anthropic, deepseek...)")
+@click.option("--reasoning", "-r", is_flag=True, help="Show only models with reasoning support.")
+@click.option("--custom", "-c", is_flag=True, help="Show only user-defined models.")
+def models_list(family: str | None, reasoning: bool, custom: bool) -> None:
+    """List registered LLM models and their capabilities.
+
+    A leading ``*`` marks user-defined models.
+
+    Examples:
+
+        promptgate models list
+
+        promptgate models list --family anthropic
+
+        promptgate models list --reasoning
+
+        promptgate models list --custom
+    """
+    from promptgate.models_registry import _REGISTRY, _USER_REGISTRY
+
+    all_rows: dict = {**_REGISTRY, **_USER_REGISTRY}  # user overrides win
+    rows = sorted(all_rows.items())
+    if family:
+        rows = [(k, v) for k, v in rows if v.family == family]
+    if reasoning:
+        rows = [(k, v) for k, v in rows if v.reasoning_mode != "none"]
+    if custom:
+        rows = [(k, v) for k, v in rows if k in _USER_REGISTRY]
+
+    if not rows:
+        click.echo("No models match the filter.")
+        return
+    _print_models_table(rows, set(_USER_REGISTRY.keys()))
+
+
+@models_group.command("add")
+@click.option("--id", "model_id", required=True, help="Unique model identifier.")
+@click.option("--family", "-f", required=True, help="Provider family (openai, anthropic, deepseek...)")
+@click.option("--ctx", "context_window", required=True, type=int, help="Context window in tokens.")
+@click.option(
+    "--reasoning", "-r", default="none",
+    type=click.Choice(["none", "chain_of_thought", "native"]),
+    help="Reasoning mode.",
+)
+@click.option(
+    "--cot-strategy", default="zero_shot",
+    type=click.Choice(["zero_shot", "structured", "react"]),
+    help="CoT algorithm for chain_of_thought models.",
+)
+@click.option("--json-native", is_flag=True, help="Model supports native JSON output mode.")
+@click.option("--no-system-prompt", is_flag=True, help="Model does not accept a system prompt.")
+@click.option("--reasoning-budget", type=int, default=None, help="Token budget for native reasoning.")
+@click.option("--max-output", type=int, default=4096, help="Max output tokens.")
+def models_add(
+    model_id: str,
+    family: str,
+    context_window: int,
+    reasoning: str,
+    cot_strategy: str,
+    json_native: bool,
+    no_system_prompt: bool,
+    reasoning_budget: int | None,
+    max_output: int,
+) -> None:
+    """Add or override a model in the user registry.
+
+    Writes to ``~/.promptgate/models.yaml``.
+
+    Examples:
+
+        promptgate models add --id gpt-5 --family openai --ctx 400000 --reasoning native
+
+        promptgate models add --id my-llm --family custom --ctx 8000 --reasoning chain_of_thought --cot-strategy structured
+    """
+    from promptgate.models_registry import ModelCapabilities, register_model
+
+    caps = ModelCapabilities(
+        family=family,
+        context_window=context_window,
+        reasoning_mode=reasoning,
+        cot_strategy=cot_strategy,
+        json_native=json_native,
+        supports_system_prompt=not no_system_prompt,
+        reasoning_budget_tokens=reasoning_budget,
+        max_output_tokens=max_output,
+    )
+    register_model(model_id, caps)
+    click.echo(f"Registered '{model_id}' ({family}, ctx={context_window:,}) → ~/.promptgate/models.yaml")
+
+
+@models_group.command("rm")
+@click.argument("model_id")
+def models_rm(model_id: str) -> None:
+    """Remove a custom model from the user registry.
+
+    Only user-defined models can be removed; built-in entries are protected.
+
+    Examples:
+
+        promptgate models rm my-custom-llm
+    """
+    from promptgate.models_registry import unregister_model
+
+    if not unregister_model(model_id):
+        raise click.ClickException(
+            f"'{model_id}' not found in user registry. Built-in models cannot be removed."
+        )
+    click.echo(f"Removed '{model_id}' from ~/.promptgate/models.yaml")
+
+
+@models_group.command("show")
+@click.argument("model_id")
+def models_show(model_id: str) -> None:
+    """Show full capabilities for a specific model.
+
+    Examples:
+
+        promptgate models show gpt-4o
+
+        promptgate models show my-custom-llm
+    """
+    from promptgate.models_registry import _USER_REGISTRY, resolve_model
+
+    caps = resolve_model(model_id)
+    if caps is None:
+        raise click.ClickException(f"Unknown model: '{model_id}'")
+
+    is_custom = model_id in _USER_REGISTRY
+    source = "user-defined" if is_custom else "built-in"
+    click.echo(f"  model_id:                {model_id}  [{source}]")
+    click.echo(f"  family:                  {caps.family}")
+    click.echo(f"  context_window:          {caps.context_window:,}")
+    click.echo(f"  max_output_tokens:       {caps.max_output_tokens:,}")
+    click.echo(f"  reasoning_mode:          {caps.reasoning_mode}")
+    click.echo(f"  cot_strategy:            {caps.cot_strategy}")
+    click.echo(f"  json_native:             {caps.json_native}")
+    click.echo(f"  supports_system_prompt:  {caps.supports_system_prompt}")
+    if caps.reasoning_budget_tokens is not None:
+        click.echo(f"  reasoning_budget_tokens: {caps.reasoning_budget_tokens:,}")
+
+
+@main.command("mcp")
+@click.option("--stdio", "transport", flag_value="stdio", default=True, help="Run MCP over stdio.")
+@click.pass_context
+def mcp_cmd(ctx: click.Context, transport: str) -> None:
+    """Start the PromptGate MCP server.
+
+    Add to Claude Desktop config:
+
+        {\"command\": \"promptgate\", \"args\": [\"mcp\", \"--stdio\"]}
+    """
+    from promptgate.mcp_adapter import run_stdio
+    run_stdio(db_path=ctx.obj["db"])
+
+
+@main.command("purge")
+@click.option("--days", default=7, show_default=True, help="Delete contracts older than N days.")
+@click.pass_context
+def purge_cmd(ctx: click.Context, days: int) -> None:
+    """Delete stale compiled contract files.
+
+    Examples:
+
+        promptgate purge --days 3
+    """
+    deleted = purge_stale(max_age_seconds=days * 86400)
+    click.echo(f"Deleted {deleted} stale contract file(s).")

promptgate/compiler.py

@@ -0,0 +1,195 @@
+"""Pydantic TypeAdapter + Jinja2 -> CompiledContract."""
+from __future__ import annotations
+
+import hashlib
+import json
+import time
+
+import jinja2.nodes
+from jinja2 import ChainableUndefined, Environment, StrictUndefined, UndefinedError
+from pydantic import TypeAdapter, ValidationError
+
+from promptgate.models import CompiledContract, ModelHints, PromptConfig
+
+
+_jinja_env = Environment(undefined=StrictUndefined, autoescape=False)
+_jinja_env_lenient = Environment(undefined=ChainableUndefined, autoescape=False)
+_jinja_env_parse = Environment(autoescape=False)  # AST analysis only — no rendering
+
+# Chain-of-thought injection templates by strategy.
+# Applied automatically when model.reasoning_mode == "chain_of_thought" and
+# the template does not already reference the `reasoning_mode` variable.
+_COT_TEMPLATES: dict[str, str] = {
+    # Kojima et al. 2022 — reliable for most instruction-tuned models
+    "zero_shot": "Think step by step before giving your final answer.\n\n",
+    # Numbered analysis — better for analytical / long-form tasks
+    "structured": (
+        "Work through this task step by step:\n"
+        "1. Understand exactly what is being asked\n"
+        "2. Identify all relevant information\n"
+        "3. Reason through the solution carefully\n"
+        "4. Formulate and verify your final answer\n\n"
+    ),
+    # Yao et al. ReAct — best for tool-use and agentic tasks
+    "react": (
+        "Use the following format for each reasoning step:\n"
+        "Thought: [your reasoning about the current step]\n"
+        "Action: [what you determine or decide]\n"
+        "Observation: [what you learn from that action]\n"
+        "... (repeat Thought/Action/Observation as needed)\n"
+        "Final Answer: [your conclusion]\n\n"
+    ),
+}
+
+
+def _schema_hash(schema: dict) -> str:
+    raw = json.dumps(schema, sort_keys=True, ensure_ascii=False)
+    return hashlib.sha256(raw.encode()).hexdigest()[:8]
+
+
+def _find_missing(schema: dict, payload: dict) -> list[str]:
+    required = schema.get("required", [])
+    return [f for f in required if f not in payload]
+
+
+def _template_references_var(template_str: str, var_name: str) -> bool:
+    """Return True if the Jinja2 template AST contains a reference to var_name.
+
+    Parses without rendering — checks Name nodes in the AST so both
+    ``{{ var_name }}`` and ``{% if var_name %}`` are detected correctly.
+
+    Args:
+        template_str: Raw Jinja2 template string.
+        var_name: Variable name to search for.
+
+    Returns:
+        True if the variable is referenced anywhere in the template.
+
+    Examples:
+        >>> _template_references_var("Hello {{ reasoning_mode }}", "reasoning_mode")
+        True
+        >>> _template_references_var("Hello world", "reasoning_mode")
+        False
+    """
+    ast = _jinja_env_parse.parse(template_str)
+    return any(node.name == var_name for node in ast.find_all(jinja2.nodes.Name))
+
+
+def compile_prompt(prompt: PromptConfig, payload: dict, model_id: str | None = None) -> CompiledContract:
+    """Validate payload against schema and render the Jinja2 template.
+
+    When ``model_id`` is provided, model capability vars are injected into the
+    Jinja2 context (``reasoning_mode``, ``model_family``, ``context_window``,
+    ``json_native``, ``model_id``).  If the model requires chain-of-thought
+    reasoning and the template does not reference ``reasoning_mode``, the
+    appropriate CoT algorithm prefix is prepended automatically.
+
+    Args:
+        prompt: The prompt configuration containing schema and template.
+        payload: Key-value data to fill into the template.
+        model_id: Optional LLM model identifier. Enables model-aware compilation
+            and CoT auto-injection for ``chain_of_thought`` models.
+
+    Returns:
+        CompiledContract with rendered system_prompt, schema_hash,
+        model_hints (if model_id provided), and any missing required fields.
+
+    Raises:
+        ValueError: If the Jinja2 template references an undefined variable
+            that is not in the payload and not in missing_fields.
+
+    Examples:
+        >>> from promptgate.models import PromptConfig
+        >>> p = PromptConfig(
+        ...     id="t", name="T",
+        ...     **{"schema": {"type": "object", "properties": {"x": {"type": "string"}}, "required": ["x"]}},
+        ...     template="Hello {{ x }}",
+        ... )
+        >>> contract = compile_prompt(p, {"x": "world"})
+        >>> contract.system_prompt
+        'Hello world'
+        >>> contract = compile_prompt(p, {"x": "world"}, model_id="gpt-4o")
+        >>> contract.model_hints.family
+        'openai'
+    """
+    from promptgate.models_registry import resolve_model
+
+    schema = prompt.schema_
+    sh = _schema_hash(schema)
+    missing = _find_missing(schema, payload)
+
+    # Resolve model capabilities (None if model_id unknown or not given)
+    caps = resolve_model(model_id) if model_id else None
+
+    # Coerce payload fields declared in schema using Pydantic TypeAdapter
+    coerced: dict = {}
+    props = schema.get("properties", {})
+    for key, value in payload.items():
+        if key in props:
+            try:
+                ta = TypeAdapter(type(value))
+                coerced[key] = ta.validate_python(value)
+            except (ValidationError, Exception):
+                coerced[key] = value
+        else:
+            coerced[key] = value
+
+    ctx = {
+        **coerced,
+        "payload_json": json.dumps(coerced, ensure_ascii=False, indent=2),
+        "output_schema": json.dumps(schema, ensure_ascii=False),
+        "missing_fields": missing,
+        # Model context vars — safe defaults when no model specified
+        "model_id": model_id or "",
+        "model_family": caps.family if caps else "",
+        "reasoning_mode": caps.reasoning_mode if caps else "none",
+        "context_window": caps.context_window if caps else 0,
+        "json_native": caps.json_native if caps else False,
+    }
+
+    try:
+        if missing:
+            # Missing required fields — use lenient rendering so contract is still created
+            tmpl = _jinja_env_lenient.from_string(prompt.template)
+            rendered = tmpl.render(**ctx)
+        else:
+            tmpl = _jinja_env.from_string(prompt.template)
+            rendered = tmpl.render(**ctx)
+    except UndefinedError as exc:
+        raise ValueError(f"Template variable error: {exc}") from exc
+
+    # Auto-inject CoT prefix when:
+    # 1. Model needs chain_of_thought reasoning
+    # 2. Template does not already reference reasoning_mode (user controls manually)
+    if (
+        caps is not None
+        and caps.reasoning_mode == "chain_of_thought"
+        and not _template_references_var(prompt.template, "reasoning_mode")
+    ):
+        cot_prefix = _COT_TEMPLATES.get(caps.cot_strategy, _COT_TEMPLATES["zero_shot"])
+        rendered = cot_prefix + rendered
+
+    model_hints: ModelHints | None = None
+    if caps is not None:
+        model_hints = ModelHints(
+            model_id=model_id,  # type: ignore[arg-type]
+            family=caps.family,
+            reasoning_mode=caps.reasoning_mode,
+            cot_strategy=caps.cot_strategy,
+            context_window=caps.context_window,
+            max_output_tokens=caps.max_output_tokens,
+            json_native=caps.json_native,
+            supports_system_prompt=caps.supports_system_prompt,
+            reasoning_budget_tokens=caps.reasoning_budget_tokens,
+        )
+
+    return CompiledContract(
+        prompt_id=prompt.id,
+        schema_hash=sh,
+        compiled_at=int(time.time()),
+        system_prompt=rendered,
+        payload=coerced,
+        missing_fields=missing,
+        model_id=model_id,
+        model_hints=model_hints,
+    )