structguard 0.1.2__tar.gz

structguard-0.1.2/.env.example

@@ -0,0 +1,25 @@
+# ---------------------------------------------------------------------------
+# StructGuard examples — dummy environment file
+# Copy to `.env` (already named .env here) and replace with your real keys.
+# Loaded automatically by each example via python-dotenv's load_dotenv().
+# NEVER commit a real .env file to version control — add it to .gitignore.
+# ---------------------------------------------------------------------------
+
+# --- Groq ---
+GROQ_API_KEY=gsk_dummy_replace_with_your_real_groq_api_key
+GROQ_MODEL=llama-3.3-70b-versatile # Replace with any other model
+
+# --- OpenAI ---
+OPENAI_API_KEY=sk-dummy_replace_with_your_real_openai_api_key
+OPENAI_MODEL=gpt-4o-mini # Replace with any other model
+
+# --- Anthropic ---
+ANTHROPIC_API_KEY=sk-ant-dummy_replace_with_your_real_anthropic_api_key
+ANTHROPIC_MODEL=claude-sonnet-4-6 # Replace with any other model
+
+# --- Google Gemini ---
+GOOGLE_API_KEY=dummy_replace_with_your_real_google_api_key
+GEMINI_MODEL=gemini-1.5-pro # Replace with any other model
+
+# --- Ollama (local, no key needed, only model name matters) ---
+OLLAMA_MODEL=llama3.1 # Replace with any other model

structguard-0.1.2/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.

structguard-0.1.2/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,84 @@
+# 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/examples/README.md

@@ -0,0 +1,42 @@
+# StructGuard Examples
+
+Each script is runnable on its own once you `pip install` the right extra and
+export the relevant API key.
+
+| Script | Shows |
+|---|---|
+| `openai_example.py` | Basic usage with OpenAI + Pydantic schema + report |
+| `anthropic_example.py` | Same, with Anthropic (drop-in client swap) |
+| `gemini_example.py` | Gemini — note on `GenerativeModel` instance requirement |
+| `groq_example.py` | Groq — note on model selection / JSON mode support |
+| `ollama_example.py` | Fully local, no API key |
+| `dataclass_example.py` | Using a stdlib `@dataclass` instead of Pydantic |
+| `typeddict_example.py` | Using `TypedDict` |
+| `json_schema_example.py` | Using a raw JSON Schema dict (no Python class) |
+| `error_handling_example.py` | Catching `RetryLimitExceeded`, `SchemaValidationError`, etc. + debug logging |
+
+## Run any example
+
+```bash
+pip install structguard[openai]      # or [anthropic], [gemini], [groq]
+export OPENAI_API_KEY=sk-...          # matching env var for the provider
+python examples/openai_example.py
+```
+
+## Gemini quirk to know
+
+`llm=` must be a `genai.GenerativeModel(...)` instance, not the `google.generativeai`
+module itself:
+
+```python
+import google.generativeai as genai
+genai.configure()
+model = genai.GenerativeModel("gemini-1.5-pro")   # <- pass this to generate()
+```
+
+## Groq quirk to know
+
+Groq's client is OpenAI-compatible (`.chat.completions.create()`), but the
+`model=` string must match a currently-hosted Groq model ID that supports
+JSON mode — check https://console.groq.com/docs/models since the lineup
+changes over time.

structguard-0.1.2/examples/anthropic_example.py

@@ -0,0 +1,63 @@
+"""
+StructGuard + Anthropic
+=========================
+Install:
+    pip install structguard[anthropic] python-dotenv
+
+Setup:
+    Put ANTHROPIC_API_KEY and ANTHROPIC_MODEL in a `.env` file next to this
+    script (see the provided dummy .env for the expected format).
+
+Run:
+    python anthropic_example.py
+"""
+import os
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from anthropic import Anthropic
+
+from structguard import generate, RetryLimitExceeded
+
+load_dotenv()
+
+MODEL_NAME = os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-6")
+
+
+class Incident(BaseModel):
+    summary: str
+    priority: str
+    confidence: float
+
+
+def main():
+    client = Anthropic()  # reads ANTHROPIC_API_KEY from env (loaded via load_dotenv above)
+
+    prompt = (
+        "Summarize this incident: Database connection pool exhausted, "
+        "causing intermittent 500 errors on the checkout service since 14:02 UTC."
+    )
+
+    try:
+        result = generate(
+            llm=client,
+            prompt=prompt,
+            schema=Incident,
+            model=MODEL_NAME,
+            max_retries=2,
+            return_report=True,
+        )
+    except RetryLimitExceeded as e:
+        print(f"Gave up after {e.attempts} attempts: {e.last_error}")
+        return
+
+    incident = result.data
+    print("Model used:", MODEL_NAME)
+    print("Summary:   ", incident.summary)
+    print("Priority:  ", incident.priority)
+    print("Confidence:", incident.confidence)
+    print()
+    print("Report:", result.report)
+
+
+if __name__ == "__main__":
+    main()

structguard-0.1.2/examples/dataclass_example.py

@@ -0,0 +1,54 @@
+"""
+StructGuard with a stdlib dataclass schema (works with any provider — Groq shown here).
+
+Install:
+    pip install structguard[groq] python-dotenv
+
+Setup:
+    Put GROQ_API_KEY and GROQ_MODEL in a `.env` file next to this script.
+
+Run:
+    python dataclass_example.py
+"""
+import os
+from dataclasses import dataclass
+from dotenv import load_dotenv
+from groq import Groq
+
+from structguard import generate
+
+load_dotenv()
+
+MODEL_NAME = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+
+
+@dataclass
+class TicketSummary:
+    title: str
+    category: str
+    urgent: bool
+
+
+def main():
+    client = Groq(api_key=os.getenv("GROQ_API_KEY"))
+
+    ticket_text = (
+        "User reports they cannot check out — payment page hangs indefinitely "
+        "after clicking 'Pay Now'. Happening for all users since this morning."
+    )
+
+    result = generate(
+        llm=client,
+        prompt=f"Classify this support ticket:\n\n{ticket_text}",
+        schema=TicketSummary,
+        model=MODEL_NAME,
+    )
+
+    print("Model used:", MODEL_NAME)
+    print(f"Title:    {result.title}")
+    print(f"Category: {result.category}")
+    print(f"Urgent:   {result.urgent}")
+
+
+if __name__ == "__main__":
+    main()

structguard-0.1.2/examples/error_handling_example.py

@@ -0,0 +1,80 @@
+"""
+StructGuard — error handling, retries, and debug logging.
+
+Install:
+    pip install structguard[anthropic] python-dotenv
+
+Setup:
+    Put ANTHROPIC_API_KEY and ANTHROPIC_MODEL in a `.env` file next to this
+    script.
+
+Run:
+    python error_handling_example.py
+"""
+import logging
+import os
+
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from anthropic import Anthropic
+
+from structguard import (
+    generate,
+    RetryLimitExceeded,
+    SchemaValidationError,
+    JsonRepairError,
+    UnsupportedProviderError,
+)
+
+load_dotenv()
+
+MODEL_NAME = os.getenv("ANTHROPIC_MODEL", "claude-sonnet-4-6")
+
+
+class Incident(BaseModel):
+    summary: str
+    priority: str
+    confidence: float
+
+
+def main():
+    # Turn on debug logging to see: raw LLM output, whether repair was applied,
+    # validation errors per attempt, and retry counts.
+    logging.basicConfig(level=logging.DEBUG)
+
+    client = Anthropic()
+
+    try:
+        result = generate(
+            llm=client,
+            prompt="Summarize this incident: API gateway returning 502s intermittently.",
+            schema=Incident,
+            model=MODEL_NAME,
+            max_retries=2,     # 3 total attempts
+            debug=True,
+            return_report=True,
+        )
+        print("Model used:", MODEL_NAME)
+        print("Success:", result.data)
+        print("Retries needed:", result.report.retries)
+
+    except RetryLimitExceeded as e:
+        # All attempts exhausted — inspect e.attempts and e.last_error
+        print(f"Gave up after {e.attempts} attempts.")
+        print("Last underlying error:", e.last_error)
+
+    except SchemaValidationError as e:
+        # Only reachable if you call validate()/generate() in a way that
+        # surfaces a single validation failure directly (e.g. max_retries=0)
+        for err in e.errors:
+            print(f"  {err['field']}: {err['issue']}")
+
+    except JsonRepairError as e:
+        print("Could not parse the model's output as JSON at all:", e.raw_output[:200])
+
+    except UnsupportedProviderError:
+        print("The `llm=` client isn't a recognized OpenAI/Anthropic/Gemini/Groq/Ollama client.")
+
+
+if __name__ == "__main__":
+    main()

structguard-0.1.2/examples/gemini_example.py

@@ -0,0 +1,78 @@
+"""
+StructGuard + Google Gemini
+==============================
+Install:
+    pip install structguard[gemini] python-dotenv
+
+Setup:
+    Put GOOGLE_API_KEY and GEMINI_MODEL in a `.env` file next to this script
+    (see the provided dummy .env for the expected format).
+
+Run:
+    python gemini_example.py
+
+IMPORTANT — Gemini client shape is different from OpenAI/Anthropic:
+    Those SDKs give you one client object you call `.chat.completions.create()`
+    or `.messages.create()` on. Gemini instead wants you to construct a
+    `GenerativeModel` instance *per model name* first, then call
+    `.generate_content()` on THAT object.
+
+    So for StructGuard, the `llm=` argument must be the `GenerativeModel`
+    instance (not the top-level `google.generativeai` module, and not the
+    result of `genai.configure(...)`, which returns None). That's why we
+    build the model using MODEL_NAME from .env below, then pass the model
+    object itself into generate().
+"""
+import os
+from dotenv import load_dotenv
+from pydantic import BaseModel
+import google.generativeai as genai
+
+from structguard import generate, RetryLimitExceeded
+
+load_dotenv()
+
+MODEL_NAME = os.getenv("GEMINI_MODEL", "gemini-1.5-pro")
+
+
+class Incident(BaseModel):
+    summary: str
+    priority: str
+    confidence: float
+
+
+def main():
+    genai.configure(api_key=os.getenv("GOOGLE_API_KEY"))
+
+    # Build the model instance yourself, using the model name from .env —
+    # this IS the object you pass as llm=.
+    model = genai.GenerativeModel(MODEL_NAME)
+
+    prompt = (
+        "Summarize this incident: Database connection pool exhausted, "
+        "causing intermittent 500 errors on the checkout service since 14:02 UTC."
+    )
+
+    try:
+        result = generate(
+            llm=model,                 # <-- the GenerativeModel instance, not the genai module
+            prompt=prompt,
+            schema=Incident,
+            max_retries=2,
+            return_report=True,
+        )
+    except RetryLimitExceeded as e:
+        print(f"Gave up after {e.attempts} attempts: {e.last_error}")
+        return
+
+    incident = result.data
+    print("Model used:", MODEL_NAME)
+    print("Summary:   ", incident.summary)
+    print("Priority:  ", incident.priority)
+    print("Confidence:", incident.confidence)
+    print()
+    print("Report:", result.report)
+
+
+if __name__ == "__main__":
+    main()

structguard-0.1.2/examples/groq_example.py

@@ -0,0 +1,77 @@
+"""
+StructGuard + Groq
+=====================
+Install:
+    pip install structguard[groq] python-dotenv
+
+Setup:
+    Put GROQ_API_KEY and GROQ_MODEL in a `.env` file next to this script
+    (see the provided dummy .env for the expected format).
+
+Run:
+    python groq_example.py
+
+NOTE on models: Groq hosts several open-weight models (Llama, Mixtral, etc.)
+behind an OpenAI-compatible chat API, so the client shape is identical to
+OpenAI's — `.chat.completions.create()`. The main thing to get right is the
+GROQ_MODEL value in your .env, since it must match one of Groq's currently
+hosted model IDs (these change over time — check
+https://console.groq.com/docs/models for the current list). Not every
+hosted model supports JSON mode; StructGuard requests
+`response_format={"type": "json_object"}` automatically, so pick a model
+that's documented as JSON-mode compatible (most current Llama 3.x models
+on Groq are).
+"""
+import os
+from dotenv import load_dotenv
+from pydantic import BaseModel
+from groq import Groq
+
+from structguard import generate, RetryLimitExceeded
+
+load_dotenv()
+
+MODEL_NAME = os.getenv("GROQ_MODEL", "llama-3.3-70b-versatile")
+
+
+class Incident(BaseModel):
+    summary: str
+    priority: str
+    confidence: float
+
+
+def main():
+    client = Groq(api_key=os.getenv("GROQ_API_KEY"))  # explicit, but Groq() also auto-reads GROQ_API_KEY
+
+    prompt = (
+        "Summarize this incident: Database connection pool exhausted, "
+        "causing intermittent 500 errors on the checkout service since 14:02 UTC."
+    )
+
+    try:
+        result = generate(
+            llm=client,
+            prompt=prompt,
+            schema=Incident,
+            model=MODEL_NAME,   # <-- pulled from GROQ_MODEL in .env
+            max_retries=2,
+            return_report=True,
+        )
+    except RetryLimitExceeded as e:
+        print(f"Gave up after {e.attempts} attempts: {e.last_error}")
+        return
+
+    incident = result.data
+    print("Model used:", MODEL_NAME)
+    print("Summary:   ", incident.summary)
+    print("Priority:  ", incident.priority)
+    print("Confidence:", incident.confidence)
+    print()
+    print("Report:", result.report)
+    print()
+    print(f"Tokens in/out: {result.report.tokens_input}/{result.report.tokens_output}"
+          "  (Groq's inference speed makes this a good fit for high-retry-tolerance pipelines)")
+
+
+if __name__ == "__main__":
+    main()