structguard 0.1.2__py3-none-any.whl

structguard/__init__.py

@@ -0,0 +1,34 @@
+"""
+StructGuard — Reliable structured outputs for production LLM applications.
+
+    from structguard import generate
+
+    incident = generate(llm=client, prompt="Summarize this incident.", schema=Incident)
+"""
+from .core import GenerationResult, generate
+from .exceptions import (
+    InvalidResponseError,
+    InvalidSchemaError,
+    JsonRepairError,
+    RetryLimitExceeded,
+    SchemaValidationError,
+    StructGuardError,
+    UnsupportedProviderError,
+)
+from .report import ValidationReport
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "generate",
+    "GenerationResult",
+    "ValidationReport",
+    "StructGuardError",
+    "SchemaValidationError",
+    "JsonRepairError",
+    "RetryLimitExceeded",
+    "UnsupportedProviderError",
+    "InvalidResponseError",
+    "InvalidSchemaError",
+    "__version__",
+]

structguard/adapters/__init__.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any
+
+from ..exceptions import UnsupportedProviderError
+from .anthropic_adapter import AnthropicAdapter
+from .base import BaseAdapter, RawCompletion
+from .gemini_adapter import GeminiAdapter
+from .groq_adapter import GroqAdapter
+from .ollama_adapter import OllamaAdapter
+from .openai_adapter import OpenAIAdapter
+
+_REGISTRY: list[type[BaseAdapter]] = [
+    OpenAIAdapter,
+    AnthropicAdapter,
+    GeminiAdapter,
+    GroqAdapter,
+    OllamaAdapter,
+]
+
+
+def resolve_adapter(client: Any, default_model: str | None = None) -> BaseAdapter:
+    """Inspect `client` and return the matching adapter instance."""
+    for adapter_cls in _REGISTRY:
+        if adapter_cls.matches(client):
+            return adapter_cls(client, default_model=default_model)
+    raise UnsupportedProviderError(
+        "Could not determine LLM provider from the client object. "
+        "Pass an OpenAI, Anthropic, Gemini, Groq, or Ollama client instance.",
+        context={"client_type": type(client).__name__},
+    )
+
+
+__all__ = ["BaseAdapter", "RawCompletion", "resolve_adapter",
+           "OpenAIAdapter", "AnthropicAdapter", "GeminiAdapter", "GroqAdapter", "OllamaAdapter"]

structguard/adapters/anthropic_adapter.py

@@ -0,0 +1,34 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .base import BaseAdapter, RawCompletion
+
+
+class AnthropicAdapter(BaseAdapter):
+    provider_name = "Anthropic"
+
+    @classmethod
+    def matches(cls, client: Any) -> bool:
+        return type(client).__module__.startswith("anthropic")
+
+    def complete(self, prompt: str, *, model: Optional[str] = None,
+                 system: Optional[str] = None, **kwargs) -> RawCompletion:
+        model = model or self.default_model or "claude-sonnet-4-6"
+        response = self.client.messages.create(
+            model=model,
+            max_tokens=kwargs.pop("max_tokens", 1024),
+            system=system or "You respond with valid JSON only, matching the requested schema.",
+            messages=[{"role": "user", "content": prompt}],
+            **kwargs,
+        )
+        text = "".join(block.text for block in response.content if getattr(block, "type", None) == "text")
+        usage = getattr(response, "usage", None)
+        return RawCompletion(
+            text=text,
+            model=model,
+            provider=self.provider_name,
+            tokens_input=getattr(usage, "input_tokens", None) if usage else None,
+            tokens_output=getattr(usage, "output_tokens", None) if usage else None,
+            raw_response=response,
+        )

structguard/adapters/base.py

@@ -0,0 +1,42 @@
+"""
+Universal LLM Adapter Layer — base interface.
+
+Every provider adapter implements `.complete(prompt, model=None, **kwargs)`
+and returns a `RawCompletion`, giving the rest of the SDK one shape to work
+with regardless of provider.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from dataclasses import dataclass
+from typing import Any, Optional
+
+
+@dataclass
+class RawCompletion:
+    text: str
+    model: str
+    provider: str
+    tokens_input: Optional[int] = None
+    tokens_output: Optional[int] = None
+    raw_response: Any = None
+
+
+class BaseAdapter(ABC):
+    provider_name: str = "base"
+
+    def __init__(self, client: Any, default_model: Optional[str] = None):
+        self.client = client
+        self.default_model = default_model
+
+    @abstractmethod
+    def complete(self, prompt: str, *, model: Optional[str] = None,
+                 system: Optional[str] = None, **kwargs) -> RawCompletion:
+        """Send `prompt` to the provider and return a RawCompletion."""
+        raise NotImplementedError
+
+    @classmethod
+    @abstractmethod
+    def matches(cls, client: Any) -> bool:
+        """Return True if `client` is an instance this adapter knows how to drive."""
+        raise NotImplementedError

structguard/adapters/gemini_adapter.py

@@ -0,0 +1,36 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .base import BaseAdapter, RawCompletion
+
+
+class GeminiAdapter(BaseAdapter):
+    provider_name = "Gemini"
+
+    @classmethod
+    def matches(cls, client: Any) -> bool:
+        return type(client).__module__.startswith("google.generativeai")
+
+    def complete(self, prompt: str, *, model: Optional[str] = None,
+                 system: Optional[str] = None, **kwargs) -> RawCompletion:
+        model_name = model or self.default_model or "gemini-1.5-pro"
+        full_prompt = f"{system}\n\n{prompt}" if system else prompt
+
+        # google-generativeai's GenerativeModel is created per-model, so if the
+        # caller passed the module/client directly we instantiate here.
+        model_obj = self.client if hasattr(self.client, "generate_content") else self.client.GenerativeModel(model_name)
+        response = model_obj.generate_content(
+            full_prompt,
+            generation_config={"response_mime_type": "application/json"},
+            **kwargs,
+        )
+        usage = getattr(response, "usage_metadata", None)
+        return RawCompletion(
+            text=response.text,
+            model=model_name,
+            provider=self.provider_name,
+            tokens_input=getattr(usage, "prompt_token_count", None) if usage else None,
+            tokens_output=getattr(usage, "candidates_token_count", None) if usage else None,
+            raw_response=response,
+        )

structguard/adapters/groq_adapter.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .base import BaseAdapter, RawCompletion
+
+
+class GroqAdapter(BaseAdapter):
+    provider_name = "Groq"
+
+    @classmethod
+    def matches(cls, client: Any) -> bool:
+        return type(client).__module__.startswith("groq")
+
+    def complete(self, prompt: str, *, model: Optional[str] = None,
+                 system: Optional[str] = None, **kwargs) -> RawCompletion:
+        model = model or self.default_model or "llama-3.3-70b-versatile"
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        response = self.client.chat.completions.create(
+            model=model,
+            messages=messages,
+            response_format={"type": "json_object"},
+            **kwargs,
+        )
+        choice = response.choices[0].message.content
+        usage = getattr(response, "usage", None)
+        return RawCompletion(
+            text=choice or "",
+            model=model,
+            provider=self.provider_name,
+            tokens_input=getattr(usage, "prompt_tokens", None) if usage else None,
+            tokens_output=getattr(usage, "completion_tokens", None) if usage else None,
+            raw_response=response,
+        )

structguard/adapters/ollama_adapter.py

@@ -0,0 +1,35 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .base import BaseAdapter, RawCompletion
+
+
+class OllamaAdapter(BaseAdapter):
+    provider_name = "Ollama"
+
+    @classmethod
+    def matches(cls, client: Any) -> bool:
+        return type(client).__module__.startswith("ollama")
+
+    def complete(self, prompt: str, *, model: Optional[str] = None,
+                 system: Optional[str] = None, **kwargs) -> RawCompletion:
+        model = model or self.default_model or "llama3.1"
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        response = self.client.chat(
+            model=model,
+            messages=messages,
+            format="json",
+            **kwargs,
+        )
+        text = response["message"]["content"] if isinstance(response, dict) else response.message.content
+        return RawCompletion(
+            text=text,
+            model=model,
+            provider=self.provider_name,
+            raw_response=response,
+        )

structguard/adapters/openai_adapter.py

@@ -0,0 +1,38 @@
+from __future__ import annotations
+
+from typing import Any, Optional
+
+from .base import BaseAdapter, RawCompletion
+
+
+class OpenAIAdapter(BaseAdapter):
+    provider_name = "OpenAI"
+
+    @classmethod
+    def matches(cls, client: Any) -> bool:
+        return type(client).__module__.startswith("openai")
+
+    def complete(self, prompt: str, *, model: Optional[str] = None,
+                 system: Optional[str] = None, **kwargs) -> RawCompletion:
+        model = model or self.default_model or "gpt-4o-mini"
+        messages = []
+        if system:
+            messages.append({"role": "system", "content": system})
+        messages.append({"role": "user", "content": prompt})
+
+        response = self.client.chat.completions.create(
+            model=model,
+            messages=messages,
+            response_format={"type": "json_object"},
+            **kwargs,
+        )
+        choice = response.choices[0].message.content
+        usage = getattr(response, "usage", None)
+        return RawCompletion(
+            text=choice or "",
+            model=model,
+            provider=self.provider_name,
+            tokens_input=getattr(usage, "prompt_tokens", None) if usage else None,
+            tokens_output=getattr(usage, "completion_tokens", None) if usage else None,
+            raw_response=response,
+        )

structguard/core.py

@@ -0,0 +1,153 @@
+"""
+Core orchestrator: the `generate()` function.
+
+This wires together every module in the pipeline:
+  1. Normalize the schema (schema/engine.py)
+  2. Augment the prompt with schema instructions (prompting below)
+  3. Call the LLM through the resolved adapter (adapters/)
+  4. Parse + repair the raw text into JSON (repair.py)
+  5. Validate against the schema (validator.py)
+  6. On failure: build corrective feedback and retry (retry.py), up to max_retries
+  7. Return the validated object (+ optional ValidationReport)
+"""
+from __future__ import annotations
+
+import json
+from typing import Any, Optional, Union
+
+from .adapters import resolve_adapter
+from .exceptions import InvalidResponseError, RetryLimitExceeded, SchemaValidationError
+from .logging_utils import (
+    configure_debug_logging,
+    log_raw_output,
+    log_repair,
+    log_retry,
+    log_success,
+    log_validation_error,
+)
+from .repair import repair_json
+from .report import ValidationReport
+from .retry import build_retry_prompt
+from .schema.engine import normalize
+from .validator import validate
+
+
+class GenerationResult:
+    """Wrapper returned when return_report=True: the object plus its report."""
+
+    def __init__(self, data: Any, report: ValidationReport):
+        self.data = data
+        self.report = report
+
+    def __repr__(self) -> str:  # pragma: no cover - cosmetic
+        return f"GenerationResult(data={self.data!r}, report={self.report})"
+
+
+def _build_schema_prompt(user_prompt: str, json_schema: dict) -> str:
+    """Provider-Independent Prompting: append schema guidance to the developer's prompt."""
+    schema_str = json.dumps(json_schema, indent=2)
+    return (
+        f"{user_prompt}\n\n"
+        "---\n"
+        "Respond with ONLY a single valid JSON object (no markdown fences, no commentary) "
+        "that strictly conforms to this JSON Schema:\n"
+        f"{schema_str}"
+    )
+
+
+def generate(
+    *,
+    llm: Any,
+    prompt: str,
+    schema: Any,
+    model: Optional[str] = None,
+    system: Optional[str] = None,
+    max_retries: int = 2,
+    debug: bool = False,
+    return_report: bool = False,
+    **provider_kwargs: Any,
+) -> Union[Any, GenerationResult]:
+    """
+    Generate a schema-validated object from an LLM.
+
+    Args:
+        llm: an initialized OpenAI / Anthropic / Gemini / Groq / Ollama client.
+        prompt: the developer's natural-language instruction.
+        schema: a Pydantic BaseModel, dataclass, TypedDict, or JSON Schema dict.
+        model: override the provider's default model.
+        system: optional system prompt.
+        max_retries: number of corrective retries after the first attempt (default 2).
+        debug: emit full lifecycle logs via the "structguard" logger.
+        return_report: if True, return a GenerationResult(data, report) instead of just data.
+        **provider_kwargs: forwarded verbatim to the underlying provider call.
+
+    Returns:
+        A validated instance of `schema` (or dict, for JSON Schema), or a
+        GenerationResult wrapping it + a ValidationReport.
+
+    Raises:
+        UnsupportedProviderError, InvalidSchemaError, JsonRepairError,
+        SchemaValidationError, RetryLimitExceeded, InvalidResponseError
+    """
+    configure_debug_logging(debug)
+
+    normalized_schema = normalize(schema)
+    adapter = resolve_adapter(llm, default_model=model)
+    report = ValidationReport(provider=adapter.provider_name, model=model or adapter.default_model or "")
+
+    current_prompt = _build_schema_prompt(prompt, normalized_schema.json_schema())
+    last_errors: list[dict] = []
+    last_exc: Optional[Exception] = None
+
+    attempts = max_retries + 1
+    for attempt in range(1, attempts + 1):
+        if attempt > 1:
+            log_retry(attempt - 1, max_retries)
+            report.retries += 1
+            current_prompt = build_retry_prompt(
+                _build_schema_prompt(prompt, normalized_schema.json_schema()), last_errors
+            )
+
+        completion = adapter.complete(current_prompt, model=model, system=system, **provider_kwargs)
+        log_raw_output(completion.text)
+
+        if not completion.text or not completion.text.strip():
+            last_exc = InvalidResponseError(
+                "LLM returned an empty response.", context={"provider": adapter.provider_name}
+            )
+            continue
+
+        try:
+            parsed, repaired = repair_json(completion.text)
+            log_repair(repaired, json.dumps(parsed) if repaired else None)
+            report.repair_applied = report.repair_applied or repaired
+        except Exception as exc:  # JsonRepairError
+            last_exc = exc
+            last_errors = [{"field": "<root>", "issue": str(exc), "type": "json_repair_error"}]
+            continue
+
+        report.mark_validation_start()
+        try:
+            validated = validate(normalized_schema, parsed, raw_output=completion.text)
+        except SchemaValidationError as exc:
+            report.mark_validation_end()
+            log_validation_error(exc.errors)
+            last_exc = exc
+            last_errors = exc.errors
+            continue
+        report.mark_validation_end()
+
+        report.tokens_input = completion.tokens_input
+        report.tokens_output = completion.tokens_output
+        report.finalize("success")
+        log_success(validated)
+
+        return GenerationResult(validated, report) if return_report else validated
+
+    report.errors = last_errors
+    report.finalize("failed")
+    raise RetryLimitExceeded(
+        f"Failed to produce a schema-valid response after {attempts} attempt(s).",
+        attempts=attempts,
+        last_error=last_exc,
+    )

structguard/exceptions.py

@@ -0,0 +1,62 @@
+"""
+Structured exception hierarchy for StructGuard.
+
+Every exception carries actionable debugging context instead of a bare message,
+so application code can log/handle failures precisely.
+"""
+from __future__ import annotations
+
+from typing import Any, Optional
+
+
+class StructGuardError(Exception):
+    """Base class for all StructGuard exceptions."""
+
+    def __init__(self, message: str, *, context: Optional[dict[str, Any]] = None):
+        self.message = message
+        self.context = context or {}
+        super().__init__(self._format())
+
+    def _format(self) -> str:
+        if not self.context:
+            return self.message
+        ctx = ", ".join(f"{k}={v!r}" for k, v in self.context.items())
+        return f"{self.message} ({ctx})"
+
+
+class UnsupportedProviderError(StructGuardError):
+    """Raised when an LLM client cannot be mapped to a known adapter."""
+
+
+class SchemaValidationError(StructGuardError):
+    """Raised when the final (possibly repaired) output fails schema validation."""
+
+    def __init__(self, message: str, *, errors: Optional[list[dict[str, Any]]] = None, raw_output: str = ""):
+        self.errors = errors or []
+        self.raw_output = raw_output
+        super().__init__(message, context={"error_count": len(self.errors)})
+
+
+class JsonRepairError(StructGuardError):
+    """Raised when the repair engine cannot turn raw text into valid JSON."""
+
+    def __init__(self, message: str, *, raw_output: str = ""):
+        self.raw_output = raw_output
+        super().__init__(message, context={"raw_output_preview": raw_output[:120]})
+
+
+class RetryLimitExceeded(StructGuardError):
+    """Raised when max_retries is exhausted without producing a valid object."""
+
+    def __init__(self, message: str, *, attempts: int, last_error: Optional[Exception] = None):
+        self.attempts = attempts
+        self.last_error = last_error
+        super().__init__(message, context={"attempts": attempts, "last_error": str(last_error) if last_error else None})
+
+
+class InvalidResponseError(StructGuardError):
+    """Raised when the LLM provider returns an empty or malformed raw response."""
+
+
+class InvalidSchemaError(StructGuardError):
+    """Raised when the schema passed to `generate()` is not a supported type."""

structguard/logging_utils.py

@@ -0,0 +1,47 @@
+"""
+Logging & Debug Mode
+=====================
+When `debug=True` is passed to `generate()`, every stage of the lifecycle
+(raw output, repaired output, validation errors, retries, final object,
+latency) is emitted through the standard `logging` module under the
+"structguard" logger, so it plugs into whatever logging setup the host
+application already has.
+"""
+from __future__ import annotations
+
+import logging
+
+logger = logging.getLogger("structguard")
+
+
+def configure_debug_logging(enabled: bool) -> None:
+    if not enabled:
+        return
+    if not logger.handlers:
+        handler = logging.StreamHandler()
+        handler.setFormatter(logging.Formatter("[structguard] %(levelname)s: %(message)s"))
+        logger.addHandler(handler)
+    logger.setLevel(logging.DEBUG)
+
+
+def log_raw_output(raw: str) -> None:
+    logger.debug("Raw LLM output:\n%s", raw)
+
+
+def log_repair(applied: bool, repaired: str | None = None) -> None:
+    if applied:
+        logger.debug("JSON repair applied. Result:\n%s", repaired)
+    else:
+        logger.debug("No JSON repair needed.")
+
+
+def log_validation_error(errors: list[dict]) -> None:
+    logger.debug("Validation failed with %d error(s): %s", len(errors), errors)
+
+
+def log_retry(attempt: int, max_retries: int) -> None:
+    logger.debug("Retrying generation (%d/%d)...", attempt, max_retries)
+
+
+def log_success(obj) -> None:
+    logger.debug("Validated object produced successfully: %r", obj)

structguard/repair.py

@@ -0,0 +1,125 @@
+"""
+Automatic JSON Repair Engine
+=============================
+LLMs frequently emit JSON that's *almost* valid: trailing commas, markdown
+code fences, single quotes, unescaped newlines, unclosed braces, etc.
+This module tries a sequence of cheap, deterministic fixes before giving up.
+
+Design note: we deliberately avoid a heavy grammar-based JSON parser here to
+keep the SDK dependency-free. Each `_fix_*` step is idempotent and safe to
+chain.
+"""
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from .exceptions import JsonRepairError
+
+
+def _strip_code_fences(text: str) -> str:
+    text = text.strip()
+    fence = re.match(r"^```(?:json)?\s*(.*?)\s*```$", text, re.DOTALL)
+    return fence.group(1) if fence else text
+
+
+def _extract_json_span(text: str) -> str:
+    """Grab the outermost {...} or [...] span, ignoring leading/trailing prose."""
+    start_candidates = [i for i in (text.find("{"), text.find("[")) if i != -1]
+    if not start_candidates:
+        return text
+    start = min(start_candidates)
+    end_brace = text.rfind("}")
+    end_bracket = text.rfind("]")
+    end = max(end_brace, end_bracket)
+    if end == -1 or end < start:
+        return text[start:]
+    return text[start : end + 1]
+
+
+def _fix_trailing_commas(text: str) -> str:
+    return re.sub(r",\s*([\]}])", r"\1", text)
+
+
+def _fix_single_quotes(text: str) -> str:
+    # Only applied as a last-resort fallback (risky if strings contain apostrophes),
+    # so it's kept separate and only used in the final repair attempt.
+    return re.sub(r"'([^']*)'", r'"\1"', text)
+
+
+def _fix_unescaped_newlines_in_strings(text: str) -> str:
+    # Collapse raw newlines/tabs that appear inside string literals.
+    out, in_string, escape = [], False, False
+    for ch in text:
+        if escape:
+            out.append(ch)
+            escape = False
+            continue
+        if ch == "\\":
+            out.append(ch)
+            escape = True
+            continue
+        if ch == '"':
+            in_string = not in_string
+            out.append(ch)
+            continue
+        if in_string and ch in ("\n", "\t"):
+            out.append("\\n" if ch == "\n" else "\\t")
+            continue
+        out.append(ch)
+    return "".join(out)
+
+
+def _fix_unclosed_braces(text: str) -> str:
+    opens = text.count("{") - text.count("}")
+    sq_opens = text.count("[") - text.count("]")
+    if opens > 0:
+        text += "}" * opens
+    if sq_opens > 0:
+        text += "]" * sq_opens
+    return text
+
+
+REPAIR_STEPS = [
+    _strip_code_fences,
+    _extract_json_span,
+    _fix_unescaped_newlines_in_strings,
+    _fix_trailing_commas,
+    _fix_unclosed_braces,
+]
+
+
+def repair_json(raw_output: str) -> tuple[dict | list, bool]:
+    """
+    Attempt to parse `raw_output` as JSON, applying repair steps as needed.
+
+    Returns (parsed_object, repair_was_applied).
+    Raises JsonRepairError if no combination of fixes yields valid JSON.
+    """
+    if not raw_output or not raw_output.strip():
+        raise JsonRepairError("Empty response from LLM; nothing to parse.", raw_output=raw_output)
+
+    # Fast path: already valid JSON.
+    try:
+        return json.loads(raw_output), False
+    except json.JSONDecodeError:
+        pass
+
+    text = raw_output
+    for step in REPAIR_STEPS:
+        text = step(text)
+        try:
+            return json.loads(text), True
+        except json.JSONDecodeError:
+            continue
+
+    # Last resort: single-quote conversion (riskier, tried last).
+    text = _fix_single_quotes(text)
+    try:
+        return json.loads(text), True
+    except json.JSONDecodeError as exc:
+        raise JsonRepairError(
+            f"Could not repair malformed JSON: {exc}",
+            raw_output=raw_output,
+        ) from exc

structguard/report.py

@@ -0,0 +1,62 @@
+"""
+Validation Report
+==================
+Rich metadata attached to every generation for logging/monitoring/debugging.
+Accessible via `result.report` when using `generate(..., return_report=True)`.
+"""
+from __future__ import annotations
+
+import time
+from dataclasses import dataclass, field
+from typing import Any, Optional
+
+
+@dataclass
+class ValidationReport:
+    status: str = "pending"          # "success" | "failed"
+    provider: str = ""
+    model: str = ""
+    retries: int = 0
+    repair_applied: bool = False
+    validation_time_ms: float = 0.0
+    total_time_ms: float = 0.0
+    tokens_input: Optional[int] = None
+    tokens_output: Optional[int] = None
+    errors: list[dict[str, Any]] = field(default_factory=list)
+
+    _start: float = field(default_factory=time.perf_counter, repr=False, compare=False)
+    _validation_start: Optional[float] = field(default=None, repr=False, compare=False)
+
+    def mark_validation_start(self) -> None:
+        self._validation_start = time.perf_counter()
+
+    def mark_validation_end(self) -> None:
+        if self._validation_start is not None:
+            self.validation_time_ms = round((time.perf_counter() - self._validation_start) * 1000, 3)
+
+    def finalize(self, status: str) -> "ValidationReport":
+        self.status = status
+        self.total_time_ms = round((time.perf_counter() - self._start) * 1000, 3)
+        return self
+
+    def to_dict(self) -> dict[str, Any]:
+        return {
+            "status": self.status,
+            "provider": self.provider,
+            "model": self.model,
+            "retries": self.retries,
+            "repair_applied": self.repair_applied,
+            "validation_time_ms": self.validation_time_ms,
+            "total_time_ms": self.total_time_ms,
+            "tokens_input": self.tokens_input,
+            "tokens_output": self.tokens_output,
+            "errors": self.errors,
+        }
+
+    def __str__(self) -> str:  # pragma: no cover - cosmetic
+        icon = "✓" if self.status == "success" else "✗"
+        return (
+            f"{icon} {self.status.capitalize()} | provider={self.provider} model={self.model} "
+            f"retries={self.retries} repair_applied={self.repair_applied} "
+            f"validation={self.validation_time_ms}ms total={self.total_time_ms}ms"
+        )

structguard/retry.py

@@ -0,0 +1,15 @@
+"""
+Intelligent Retry Engine
+==========================
+On validation failure, builds targeted corrective feedback (exact fields and
+error reasons) and re-prompts the model, instead of retrying blindly.
+"""
+from __future__ import annotations
+
+from .validator import errors_to_feedback_prompt
+
+
+def build_retry_prompt(original_prompt: str, errors: list[dict]) -> str:
+    """Compose the next attempt's prompt: original instructions + corrective feedback."""
+    feedback = errors_to_feedback_prompt(errors)
+    return f"{original_prompt}\n\n---\n{feedback}"

structguard/schema/__init__.py

@@ -0,0 +1,3 @@
+from .engine import NormalizedSchema, normalize
+
+__all__ = ["NormalizedSchema", "normalize"]

structguard/schema/engine.py

@@ -0,0 +1,100 @@
+"""
+Schema Engine
+=============
+Normalizes four different schema styles (Pydantic BaseModel, stdlib dataclass,
+TypedDict, raw JSON Schema dict) into one internal representation so the rest
+of the SDK (validator, repair, prompting) doesn't need to care which style the
+developer used.
+"""
+from __future__ import annotations
+
+import dataclasses
+import json
+import typing
+from typing import Any, Type, Union
+
+from pydantic import BaseModel, TypeAdapter, ValidationError
+
+from ..exceptions import InvalidSchemaError
+
+
+class NormalizedSchema:
+    """
+    Wraps any supported schema type behind a single interface:
+      - .json_schema()      -> dict, for prompt injection
+      - .validate(data)     -> instance (or dict for JSON Schema mode)
+      - .kind                -> "pydantic" | "dataclass" | "typeddict" | "json_schema"
+    """
+
+    def __init__(self, schema: Any):
+        self.original = schema
+        self.kind, self._adapter, self._target = self._resolve(schema)
+
+    # ---- resolution -------------------------------------------------
+
+    @staticmethod
+    def _resolve(schema: Any):
+        # 1. Pydantic BaseModel subclass
+        if isinstance(schema, type) and issubclass(schema, BaseModel):
+            return "pydantic", TypeAdapter(schema), schema
+
+        # 2. stdlib dataclass
+        if dataclasses.is_dataclass(schema) and isinstance(schema, type):
+            return "dataclass", TypeAdapter(schema), schema
+
+        # 3. TypedDict (detected via __required_keys__/__annotations__ pattern)
+        if isinstance(schema, type) and hasattr(schema, "__annotations__") and hasattr(schema, "__total__"):
+            return "typeddict", TypeAdapter(schema), schema
+
+        # 4. Raw JSON Schema dict
+        if isinstance(schema, dict) and ("type" in schema or "properties" in schema):
+            return "json_schema", None, schema
+
+        raise InvalidSchemaError(
+            "Unsupported schema type. Use a Pydantic BaseModel, a dataclass, "
+            "a TypedDict, or a raw JSON Schema dict.",
+            context={"schema_repr": repr(schema)[:200]},
+        )
+
+    # ---- public API ---------------------------------------------------
+
+    def json_schema(self) -> dict:
+        """Return a JSON-Schema dict describing the expected output shape."""
+        if self.kind == "json_schema":
+            return self._target
+        return self._adapter.json_schema()
+
+    def validate(self, data: dict) -> Any:
+        """
+        Validate `data` against the schema.
+        Returns a Pydantic/dataclass instance for those kinds, or the raw
+        dict (unchanged) for json_schema kind since there's no Python class
+        to instantiate.
+        Raises pydantic.ValidationError on failure (caller wraps it).
+        """
+        if self.kind == "json_schema":
+            # Lightweight structural check via pydantic's generic validator
+            TypeAdapter(dict).validate_python(data)
+            self._check_json_schema(data, self._target)
+            return data
+        return self._adapter.validate_python(data)
+
+    @staticmethod
+    def _check_json_schema(data: dict, schema: dict) -> None:
+        """Minimal required-field + type check for raw JSON Schema dicts."""
+        required = schema.get("required", [])
+        missing = [f for f in required if f not in data]
+        if missing:
+            raise ValidationError.from_exception_data(
+                "JSONSchema",
+                [{"type": "missing", "loc": (f,), "input": data} for f in missing],
+            )
+
+    def field_names(self) -> list[str]:
+        if self.kind == "json_schema":
+            return list(self._target.get("properties", {}).keys())
+        return list(self.json_schema().get("properties", {}).keys())
+
+
+def normalize(schema: Any) -> NormalizedSchema:
+    return NormalizedSchema(schema)

structguard/validator.py

@@ -0,0 +1,59 @@
+"""
+Intelligent Output Validator
+==============================
+Runs the parsed/repaired JSON object through the schema engine and turns
+pydantic's ValidationError into a compact, LLM-readable error list that the
+retry engine can feed back as corrective feedback.
+"""
+from __future__ import annotations
+
+from typing import Any
+
+from pydantic import ValidationError
+
+from .exceptions import SchemaValidationError
+from .schema.engine import NormalizedSchema
+
+
+def validate(schema: NormalizedSchema, data: dict, raw_output: str = "") -> Any:
+    """
+    Validate `data` against `schema`.
+    Returns the validated instance (or dict for json_schema kind).
+    Raises SchemaValidationError with a structured `.errors` list on failure.
+    """
+    try:
+        return schema.validate(data)
+    except ValidationError as exc:
+        raise SchemaValidationError(
+            f"Output failed schema validation with {exc.error_count()} error(s).",
+            errors=format_errors(exc),
+            raw_output=raw_output,
+        ) from exc
+
+
+def format_errors(exc: ValidationError) -> list[dict[str, Any]]:
+    """Convert pydantic errors into a compact, serializable list."""
+    formatted = []
+    for err in exc.errors():
+        formatted.append(
+            {
+                "field": ".".join(str(p) for p in err["loc"]) or "<root>",
+                "issue": err["msg"],
+                "type": err["type"],
+            }
+        )
+    return formatted
+
+
+def errors_to_feedback_prompt(errors: list[dict[str, Any]]) -> str:
+    """
+    Render validation errors as the corrective feedback message sent back
+    to the LLM on retry (see spec section "Intelligent Retry Engine").
+    """
+    lines = ["Your previous response failed schema validation.", "", "Errors:"]
+    for e in errors:
+        lines.append(f"- {e['field']}: {e['issue']}")
+    lines.append("")
+    lines.append("Please regenerate a complete, valid JSON object that fixes every error above. "
+                  "Return ONLY the JSON object, with no commentary or markdown formatting.")
+    return "\n".join(lines)

structguard-0.1.2.dist-info/METADATA

@@ -0,0 +1,126 @@
+Metadata-Version: 2.4
+Name: structguard
+Version: 0.1.2
+Summary: Reliable, provider-agnostic structured outputs for production LLM applications.
+Project-URL: Homepage, https://github.com/yourusername/structguard
+Project-URL: Repository, https://github.com/yourusername/structguard
+Project-URL: Issues, https://github.com/yourusername/structguard/issues
+Author-email: Sujan Ghosh <rupubally@gmail.com>
+License: MIT
+License-File: LICENSE
+Keywords: anthropic,gemini,json,llm,openai,pydantic,structured-output,validation
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.9
+Requires-Dist: pydantic>=2.0
+Provides-Extra: all
+Requires-Dist: anthropic>=0.30; extra == 'all'
+Requires-Dist: google-generativeai>=0.5; extra == 'all'
+Requires-Dist: groq>=0.5; extra == 'all'
+Requires-Dist: openai>=1.0; extra == 'all'
+Provides-Extra: anthropic
+Requires-Dist: anthropic>=0.30; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: build; extra == 'dev'
+Requires-Dist: pytest-cov; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: twine; extra == 'dev'
+Provides-Extra: gemini
+Requires-Dist: google-generativeai>=0.5; extra == 'gemini'
+Provides-Extra: groq
+Requires-Dist: groq>=0.5; extra == 'groq'
+Provides-Extra: openai
+Requires-Dist: openai>=1.0; extra == 'openai'
+Description-Content-Type: text/markdown
+
+# StructGuard
+
+**Reliable, provider-agnostic structured outputs for production LLM applications.**
+
+StructGuard makes sure every LLM response conforms to a schema you define —
+`Pydantic`, `dataclass`, `TypedDict`, or raw JSON Schema — before it reaches
+your application code. It handles prompting, JSON repair, validation, and
+intelligent retries in one call, across OpenAI, Anthropic, Gemini, Groq, and
+Ollama.
+
+## Install
+
+```bash
+pip install structguard              # core only
+pip install structguard[openai]      # + OpenAI SDK
+pip install structguard[anthropic]   # + Anthropic SDK
+pip install structguard[all]         # every provider SDK
+```
+
+## Quick start
+
+```python
+from pydantic import BaseModel
+from openai import OpenAI
+from structguard import generate
+
+class Incident(BaseModel):
+    summary: str
+    priority: str
+    confidence: float
+
+client = OpenAI()
+
+incident = generate(
+    llm=client,
+    prompt="Summarize this incident: Database connection pool exhausted, causing 500s.",
+    schema=Incident,
+)
+
+print(incident.summary, incident.priority, incident.confidence)
+```
+
+## With a full report
+
+```python
+result = generate(llm=client, prompt=prompt, schema=Incident, return_report=True)
+print(result.data)
+print(result.report)   # ✓ Success | provider=OpenAI model=gpt-4o-mini retries=0 ...
+```
+
+## Error handling
+
+```python
+from structguard import RetryLimitExceeded, SchemaValidationError
+
+try:
+    incident = generate(llm=client, prompt=prompt, schema=Incident, max_retries=2)
+except RetryLimitExceeded as e:
+    print(f"Gave up after {e.attempts} attempts: {e.last_error}")
+```
+
+## Supported schema types
+
+- `pydantic.BaseModel`
+- stdlib `@dataclass`
+- `TypedDict`
+- raw JSON Schema `dict`
+
+## Supported providers
+
+OpenAI · Anthropic · Google Gemini · Groq · Ollama
+
+## Development
+
+```bash
+git clone https://github.com/sujanrupu/structguard
+cd structguard
+pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT

structguard-0.1.2.dist-info/RECORD

@@ -0,0 +1,21 @@
+structguard/__init__.py,sha256=wJWPmdamBxEMRR3I3HG1ttEsNuZ8yig5VNPbe4qh1vw,805
+structguard/core.py,sha256=fjtTuQ09GaMRm0wzKnTSARh-x8M8DqKWtRfDcVVHveU,5617
+structguard/exceptions.py,sha256=K8AIKDGCahr3HvNenCrVroRXLfOud5u5lhyMLiLYaqw,2245
+structguard/logging_utils.py,sha256=fIE6IQkhwdUMUq5yq-i0AJ3dhtLCVCl4PJmvuB3NeMI,1437
+structguard/repair.py,sha256=hgarjb3BMzXFgOE7YqWOHENdcPJUfaIC4IrOpUxUDXI,3748
+structguard/report.py,sha256=Um2LcvtkL0loqh6VADoUomBprHIGX7Hx_CSsplXCgoA,2293
+structguard/retry.py,sha256=GIpcBWG1ZgidxUVvKrzrf4rdmkBQKUV-7Kz5Ey9I_wg,557
+structguard/validator.py,sha256=-pp4hrXprWYkgQRVShw1ljxWsQhzrzwWccnKYvM0dUo,2076
+structguard/adapters/__init__.py,sha256=A62NWPmHDvjxj2W5dTCFg6bPpRXA8XFSlM1yiHWjmZw,1207
+structguard/adapters/anthropic_adapter.py,sha256=DIYBEsoJgppWifi1cbA0Wrukc4YnJkvXz0ZaT-iJHTs,1324
+structguard/adapters/base.py,sha256=YiZOJ8q2_hcm_Wvi8ejP-rvJ0nldPIgTDKhf5nbyrRY,1242
+structguard/adapters/gemini_adapter.py,sha256=QwKEbFFp2UZNr0l8Z10mQANoNtcFH2S9-5F9FQlDX4o,1464
+structguard/adapters/groq_adapter.py,sha256=6KkDXSdOj6ccXLl8W7cDre-gs47jXyJrtKhzIBKkqcQ,1324
+structguard/adapters/ollama_adapter.py,sha256=R9hUnqBO8BXOD_SLfdLyDrCRCPScLaS4RIB44GgSxwM,1095
+structguard/adapters/openai_adapter.py,sha256=0dfWUxfc3iWNHtpO9m6ZJI0QpDhrkMHABEEyBusM9r8,1318
+structguard/schema/__init__.py,sha256=Gp2dslBmGEvvMPZ3oLX5fYwvnv-I7U2ANWrB7aPdRCw,93
+structguard/schema/engine.py,sha256=MP74RlrolypJwjusf2urQ6fgyLPkQcC7nN2Cy8LMWkE,3809
+structguard-0.1.2.dist-info/METADATA,sha256=LigNWqgXArflmPrn3X_lgUPVG7bOvRaOGtgBIiK8z6U,3694
+structguard-0.1.2.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
+structguard-0.1.2.dist-info/licenses/LICENSE,sha256=kmBbnNtygbUFZj4Om0JztNUr5QbPNgDERhWR6qitAnE,1068
+structguard-0.1.2.dist-info/RECORD,,

structguard-0.1.2.dist-info/WHEEL

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

structguard-0.1.2.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Sujan Ghosh
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.