outputguard 0.2.0__tar.gz

outputguard-0.2.0/.github/workflows/ci.yml

@@ -0,0 +1,84 @@
+name: CI
+
+on:
+  push:
+    branches: [main, master]
+    tags: ["v*"]
+  pull_request:
+    branches: [main, master]
+
+permissions:
+  contents: read
+
+jobs:
+  test:
+    runs-on: ${{ matrix.os }}
+    strategy:
+      fail-fast: false
+      matrix:
+        os: [ubuntu-latest, macos-latest, windows-latest]
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python ${{ matrix.python-version }}
+        run: uv python install ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Run tests
+        run: uv run pytest tests/ -v --tb=short --cov=outputguard --cov-report=term-missing
+
+  lint:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Install dependencies
+        run: uv sync --dev
+      - name: Check formatting
+        run: uv run ruff format --check .
+      - name: Lint
+        run: uv run ruff check .
+      - name: Type check
+        run: uv run mypy outputguard/ --ignore-missing-imports
+
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v4
+      - name: Set up Python
+        run: uv python install 3.12
+      - name: Build package
+        run: uv build
+      - name: Verify dist contents
+        run: ls -la dist/
+      - name: Upload build artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: [test, lint, build]
+    runs-on: ubuntu-latest
+    if: startsWith(github.ref, 'refs/tags/v')
+    permissions:
+      id-token: write
+    environment:
+      name: pypi
+      url: https://pypi.org/project/outputguard/
+    steps:
+      - name: Download build artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

outputguard-0.2.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+*.egg-info/
+dist/
+build/
+.venv/
+.pytest_cache/
+.coverage

outputguard-0.2.0/.python-version

@@ -0,0 +1 @@
+3.10

outputguard-0.2.0/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
+and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## [0.2.0] - Unreleased
+
+### Added
+- `fix_truncated` strategy: recovers JSON truncated by token limits
+- `fix_ellipsis` strategy: replaces `...` placeholders with valid JSON
+- `fix_unicode` strategy: fixes malformed Unicode escape sequences
+- `fix_booleans` strategy: converts Python True/False/None to JSON true/false/null
+- `parse()` convenience function: validate-repair-parse in one call, raises on failure
+- `OutputGuard.parse()` method with same behavior
+- Exception hierarchy: `OutputGuardError`, `ParseError`, `SchemaValidationError`, `RepairError`
+- `RepairReport` with diff output, confidence scoring, and step-by-step strategy tracking
+- `--diff` flag for CLI validate and repair commands
+- `--verbose` flag for CLI showing each strategy's effect
+- Strategy descriptions shown in `outputguard strategies` table
+- GitHub Actions CI (Python 3.10-3.13, Linux/macOS/Windows)
+- `py.typed` marker for PEP 561
+- Comprehensive edge-case test suite
+- Examples directory with usage patterns
+- CONTRIBUTING.md guide
+
+## [0.1.0] - 2025-01-01
+
+### Added
+- Initial release
+- 9 core repair strategies: strip_fences, extract_json, remove_comments, fix_commas, fix_quotes, fix_keys, fix_values, fix_closers, fix_newlines
+- JSON Schema validation with detailed error paths
+- Validate-and-repair pipeline
+- Retry prompt generation for LLM feedback loops
+- Click CLI with validate, repair, retry-prompt, and strategies commands
+- Library API: validate(), repair(), validate_and_repair(), retry_prompt()
+- Configurable OutputGuard class with strategy selection

outputguard-0.2.0/CONTRIBUTING.md

@@ -0,0 +1,89 @@
+# Contributing to outputguard
+
+Thanks for your interest in contributing! Here's how to get started.
+
+## Development Setup
+
+1. Clone the repository:
+   ```bash
+   git clone https://github.com/ndcorder/outputguard.git
+   cd outputguard
+   ```
+
+2. Install [uv](https://docs.astral.sh/uv/):
+   ```bash
+   curl -LsSf https://astral.sh/uv/install.sh | sh
+   ```
+
+3. Install dependencies:
+   ```bash
+   uv sync --dev
+   ```
+
+4. Run the tests:
+   ```bash
+   uv run pytest tests/ -v
+   ```
+
+## Making Changes
+
+1. Create a branch: `git checkout -b feat/my-feature`
+2. Make your changes
+3. Run the test suite: `uv run pytest tests/ -v`
+4. Commit with a descriptive message: `git commit -m "feat: add xyz"`
+
+## Adding a Repair Strategy
+
+outputguard's architecture makes it easy to add new repair strategies:
+
+1. Create `outputguard/strategies/your_strategy.py`:
+   ```python
+   NAME = "your_strategy"
+   DESCRIPTION = "What this strategy does"
+
+   def apply(text: str) -> str:
+       # Your repair logic here
+       # MUST: return text unchanged if nothing to fix
+       # MUST: never raise exceptions
+       return text
+   ```
+
+2. Register it in `outputguard/strategies/__init__.py`:
+   - Import your module
+   - Add `(your_strategy.NAME, your_strategy.apply)` to `ALL_STRATEGIES`
+   - Add the description to `STRATEGY_DESCRIPTIONS`
+
+3. Create tests in `tests/test_strategies/test_your_strategy.py`
+
+4. Run the full suite to make sure nothing breaks
+
+## Commit Messages
+
+We follow [Conventional Commits](https://www.conventionalcommits.org/):
+
+- `feat:` -- new feature
+- `fix:` -- bug fix
+- `docs:` -- documentation changes
+- `test:` -- test additions or fixes
+- `refactor:` -- code changes that neither fix a bug nor add a feature
+- `chore:` -- maintenance tasks
+
+## Code Style
+
+- We use `ruff` for linting and formatting
+- Type hints are encouraged
+- No comments unless the WHY is non-obvious
+- Keep functions focused and small
+
+## Testing
+
+- Every new feature needs tests
+- Every bug fix needs a regression test
+- Run `uv run pytest tests/ -v --tb=short` before submitting
+
+## Pull Requests
+
+- Keep PRs focused -- one feature or fix per PR
+- Include a clear description of what changed and why
+- Make sure all tests pass
+- Update README.md if adding user-facing features

outputguard-0.2.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 outputguard contributors
+
+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.

outputguard-0.2.0/MARKETING.md

@@ -0,0 +1,330 @@
+# outputguard — Launch Plan
+
+Ready-to-post content for each platform. Copy, paste, adjust as needed.
+
+---
+
+## Reddit
+
+### r/Python (largest reach, most critical audience)
+
+**Title:** `I built a library that fixes broken JSON from LLMs — 13 repair strategies, zero dependencies on any LLM provider`
+
+**Body:**
+
+If you've built anything with LLMs that expects JSON back, you know the pain. They wrap it in markdown fences. They use single quotes. They add trailing commas. They output Python `True` instead of `true`. They hit the token limit and give you truncated JSON. They add "Here's the JSON you requested!" before and after.
+
+I got tired of writing the same `try/except json.loads` + regex cleanup in every project, so I built **outputguard**.
+
+```python
+import outputguard
+
+# LLM gave you this mess:
+llm_output = """```json
+{name: 'Alice', age: 30, active: True,}
+```"""
+
+# One line to fix it:
+data = outputguard.parse(llm_output, schema)
+# → {'name': 'Alice', 'age': 30, 'active': True}
+```
+
+It handles 13 different failure modes I've collected from real LLM outputs:
+
+- Markdown code fences
+- Commentary text before/after JSON
+- JS-style comments inside JSON
+- Trailing commas
+- Single quotes instead of double
+- Unquoted object keys
+- `NaN`, `Infinity`, `undefined`
+- Python `True`/`False`/`None`
+- Truncated JSON (token limit cutoffs)
+- `...` placeholders
+- Malformed Unicode escapes
+- Missing closing braces/brackets
+- Unescaped newlines in strings
+
+It also validates against JSON Schema, generates retry prompts you can send back to the LLM, and has a CLI with `--verbose` mode that shows you exactly what each strategy changed:
+
+```
+$ echo '{name: \"Alice\", age: 30,}' | outputguard repair - --verbose
+⚠ Repaired  strategies: fix_commas, fix_keys
+
+=== fix_commas ===
+- {name: "Alice", age: 30,}
++ {name: "Alice", age: 30}
+
+=== fix_keys ===
+- {name: "Alice", age: 30}
++ {"name": "Alice", "age": 30}
+
+Confidence: 72%
+```
+
+**Why not just use `json.loads` with some regex?** You can, and I did for a year. But the edge cases compound — single quotes with apostrophes inside, comments that look like URLs, braces inside string values. Each strategy handles these correctly.
+
+Pure Python, 3 runtime deps (click, jsonschema, rich), works with any LLM provider. MIT licensed.
+
+- GitHub: https://github.com/ndcorder/outputguard
+- `pip install outputguard`
+
+Happy to answer questions about the implementation. The repair strategies are each their own module if you want to look at how they work.
+
+---
+
+### r/LocalLLaMA
+
+**Title:** `outputguard — automatically fixes broken JSON from local models (13 repair strategies for common failures)`
+
+**Body:**
+
+Local models are especially bad at producing valid JSON. Even with grammar-constrained generation, you still get trailing commas, Python-style booleans, truncated output from context limits, and markdown fences.
+
+I built a Python library that catches and repairs all of these automatically:
+
+```python
+import outputguard
+
+# Your local model returned this:
+llm_output = "{name: 'Alice', age: 30, active: True,}"
+
+# Fix and validate in one call:
+data = outputguard.parse(llm_output, your_schema)
+```
+
+13 repair strategies, runs in <1ms, works offline, no API calls. Especially useful if you're building agents or tool-calling workflows where the model needs to return structured data.
+
+Also has retry prompt generation — if repair isn't enough, it generates a correction prompt you can feed back to the model with specific error details.
+
+`pip install outputguard` | https://github.com/ndcorder/outputguard
+
+---
+
+### r/ChatGPTCoding / r/ClaudeAI
+
+**Title:** `Stop fighting with broken JSON from LLMs — outputguard fixes it automatically`
+
+**Body:**
+
+Quick share — I built a Python library that handles the "LLM returned garbage JSON" problem.
+
+You know when ChatGPT/Claude wraps JSON in markdown fences, adds helpful commentary around it, uses single quotes, or just truncates mid-output? This fixes all of that:
+
+```python
+import outputguard
+
+result = outputguard.validate_and_repair(llm_output, schema)
+if result.valid:
+    print(result.data)  # clean, validated dict
+    print(result.strategies_applied)  # what it fixed
+```
+
+13 different repair strategies, JSON Schema validation, and if repair isn't enough, it generates a retry prompt you can send back to the model.
+
+https://github.com/ndcorder/outputguard
+
+---
+
+### r/ExperiencedDevs or r/programming
+
+**Title:** `outputguard: a repair pipeline for LLM JSON output (13 strategies, schema validation, retry prompts)`
+
+**Body:**
+
+Structured output from LLMs is unreliable. Even with system prompts demanding "return only valid JSON," models produce markdown fences, trailing commas, JavaScript literals, Python-style booleans, and truncated output.
+
+I built outputguard — a repair pipeline that applies 13 strategies in order, validates against JSON Schema, and optionally generates correction prompts for retry loops.
+
+The architecture is intentionally simple: each strategy is a pure `str → str` function, applied in sequence. The repairer tries all strategies first, then falls back to one-at-a-time with parse attempts between each. There's a `RepairReport` that gives you diffs and a confidence score.
+
+The interesting engineering decisions:
+- Strategies must be string-safe (e.g., `remove_comments` can't strip `://` from URLs inside strings, `fix_values` can't replace `NaN` inside string values)
+- `fix_truncated` handles the "ran out of tokens" case by closing open strings, completing partial key-value pairs, and balancing braces
+- The CLI `--verbose` mode shows each strategy's diff — useful for debugging why a particular repair succeeded or failed
+
+3 dependencies (click, jsonschema, rich). 162 tests. MIT.
+
+https://github.com/ndcorder/outputguard
+
+---
+
+## Hacker News
+
+**Title:** `Show HN: Outputguard – Fix broken JSON from LLMs (13 repair strategies)`
+
+**URL:** `https://github.com/ndcorder/outputguard`
+
+**Top comment (post immediately after submitting):**
+
+Hi HN, I built this because every project I've worked on that uses LLMs for structured output eventually accumulates the same pile of JSON-fixing regexes.
+
+The core idea: apply a pipeline of repair strategies (strip markdown fences → extract JSON from commentary → remove JS comments → fix trailing commas → fix quotes → quote keys → fix JS values → fix Python booleans → handle truncation → fix ellipsis placeholders → fix Unicode escapes → balance braces → escape newlines), validate against JSON Schema, and optionally generate a retry prompt.
+
+Each strategy is a standalone module with a simple `apply(text: str) -> str` interface. The tricky parts were making them string-aware — you can't just regex-replace `NaN` if it appears inside a string value like `"NaN means Not a Number"`.
+
+Works with any LLM provider, no vendor dependencies. 162 tests, runs in <1ms.
+
+---
+
+## Twitter/X
+
+### Launch tweet
+
+```
+Just released outputguard — a Python library that fixes broken JSON from LLMs.
+
+13 repair strategies for the stuff LLMs actually do:
+→ markdown fences
+→ trailing commas
+→ Python True/False/None
+→ truncated output
+→ commentary text
+→ unquoted keys
+→ and 7 more
+
+One line: data = outputguard.parse(llm_output, schema)
+
+pip install outputguard
+https://github.com/ndcorder/outputguard
+```
+
+### Follow-up thread
+
+```
+The --verbose CLI mode shows exactly what each strategy changed:
+
+[screenshot of the verbose output]
+
+Useful for debugging why a repair succeeded or failed.
+```
+
+```
+My favorite feature: retry prompt generation.
+
+If repair isn't enough, outputguard generates a correction prompt with specific error details you can send back to the LLM.
+
+The LLM gets told exactly what's wrong + what the schema expects.
+```
+
+```
+162 tests. 3 dependencies. <1ms repair time. MIT licensed.
+
+Works with OpenAI, Anthropic, local models, or anything that produces text.
+```
+
+---
+
+## LinkedIn
+
+```
+I just open-sourced outputguard — a Python library that solves a problem every AI developer hits: broken JSON from LLMs.
+
+When you ask an LLM to return structured JSON, you get:
+• Markdown code fences wrapped around it
+• Single quotes instead of double quotes
+• Python True/False instead of JSON true/false
+• Trailing commas
+• Helpful commentary before and after the JSON
+• Truncated output when the model hits token limits
+
+outputguard automatically detects and repairs all of these (13 strategies total), validates against your JSON Schema, and generates retry prompts when repair isn't enough.
+
+One line to go from broken LLM output to clean, validated data:
+
+data = outputguard.parse(llm_output, schema)
+
+It's provider-agnostic (works with OpenAI, Anthropic, local models), has 162 tests, and runs in under a millisecond.
+
+If you're building AI applications that need reliable structured output, check it out:
+https://github.com/ndcorder/outputguard
+
+pip install outputguard
+
+#Python #AI #LLM #OpenSource #DeveloperTools
+```
+
+---
+
+## Dev.to / Hashnode blog post
+
+**Title:** `I Fixed the "LLMs Can't Return Valid JSON" Problem — Here's How`
+
+**Outline:**
+
+1. **The problem** (2 paragraphs) — Every AI app needs structured output. LLMs are terrible at it. Show 5-6 real examples of broken JSON from different models.
+
+2. **The naive solution** (1 paragraph) — `try/except json.loads` + growing pile of regexes. Works until it doesn't.
+
+3. **The outputguard approach** (2 paragraphs) — Pipeline of 13 repair strategies, each handling one failure mode. Show the architecture diagram: strategies are composable `str → str` functions.
+
+4. **Code walkthrough** (3 examples)
+   - Basic: `parse()` one-liner
+   - Intermediate: `validate_and_repair()` with strategy inspection
+   - Advanced: retry loop with prompt generation
+
+5. **The hard parts** (2 paragraphs) — String awareness (can't replace tokens inside JSON strings), truncation recovery (closing open strings + partial values), strategy ordering.
+
+6. **Results** — Before/after table. "Here's what 8 real LLM outputs looked like, and what outputguard did with them" (use the batch_processing.py example output).
+
+7. **Try it** — `pip install outputguard`, link to GitHub.
+
+---
+
+## Where to post (priority order)
+
+| Platform | Subreddit/Section | When | Notes |
+|---|---|---|---|
+| Reddit | r/Python | Day 1 | Largest Python community. Post as "Show r/Python". |
+| Hacker News | Show HN | Day 1 | Post the GitHub URL. Comment immediately with context. |
+| Reddit | r/LocalLLaMA | Day 1-2 | Very active, loves tools for local models. |
+| Twitter/X | Your account | Day 1 | Thread format. Tag #Python #AI #LLM. |
+| Reddit | r/MachineLearning | Day 2-3 | Post as [P] project tag. More academic audience. |
+| LinkedIn | Your profile | Day 1-2 | Professional audience. |
+| Reddit | r/ChatGPTCoding | Day 2-3 | Practical coding audience. |
+| Dev.to | Blog post | Day 3-5 | Longer-form content, good for SEO. |
+| Reddit | r/artificial | Day 3-5 | Broader AI audience. |
+| Reddit | r/OpenSource | Day 3-5 | OSS-focused community. |
+
+**Timing tips:**
+- Post on Tuesday-Thursday, 9-11am EST (peak Reddit/HN traffic)
+- Don't post everywhere on the same day — spread over a week
+- Engage with every comment. Answer questions thoroughly.
+- If HN gets traction, don't post Reddit the same day (split your attention)
+
+**What NOT to do:**
+- Don't use marketing language ("revolutionary", "game-changing")
+- Don't compare to paid products
+- Don't post and disappear — respond to every comment
+- Don't astroturf or ask friends to upvote
+- Don't cross-post the exact same text
+
+---
+
+## Demo GIF / Screenshot
+
+The single most impactful thing for social posts is a terminal screenshot or GIF showing the `--verbose` repair output. Run this and capture it with a tool like [vhs](https://github.com/charmbracelet/vhs) or just a screenshot:
+
+```bash
+echo '{name: '"'"'Alice'"'"', age: 30, active: True,}' | outputguard repair - --verbose
+```
+
+This produces colorized output showing each strategy's diff — it's visually compelling and immediately communicates what the tool does.
+
+For Reddit, a terminal screenshot in the post body gets 2-3x more engagement than text-only.
+
+---
+
+## Responding to common objections
+
+**"Why not just use Pydantic + instructor?"**
+> Instructor is great if you're using OpenAI's API. outputguard works at a different layer — it fixes the raw text before parsing, works with any provider (including local models), and doesn't require you to change your LLM client. They're complementary, not competing.
+
+**"Just use structured output / function calling"**
+> Structured output modes help a lot but aren't available everywhere (local models, older APIs), don't prevent truncation, and some models still break the schema. outputguard is the safety net for when the LLM doesn't cooperate.
+
+**"I just use a try/except with some regex"**
+> That works until you hit apostrophes in single-quoted strings, URLs in comment-stripped JSON, or braces inside string values. Each of these is a 30-minute debugging session. outputguard has 162 tests for these edge cases.
+
+**"Seems over-engineered for a simple problem"**
+> The API is one function: `data = outputguard.parse(text, schema)`. The complexity is behind the scenes. You don't need to know about the 13 strategies unless you want to.