confident-extract 0.1.0a1__tar.gz

confident_extract-0.1.0a1/.github/ISSUE_TEMPLATE/config.yml

@@ -0,0 +1,5 @@
+blank_issues_enabled: true
+contact_links:
+  - name: Contribution guide
+    url: https://github.com/hitarthbuilds/confident-extract/blob/master/CONTRIBUTING.md
+    about: Read local setup, quality gates, benchmark guidance, and release checks before opening a change.

confident_extract-0.1.0a1/.github/workflows/ci.yml

@@ -0,0 +1,43 @@
+name: CI
+
+on:
+  pull_request:
+  push:
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version:
+          - "3.11"
+          - "3.12"
+          - "3.13"
+
+    steps:
+      - name: Check out repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+          cache: pip
+
+      - name: Install package and development dependencies
+        run: |
+          python -m pip install --upgrade pip
+          python -m pip install -e ".[dev]"
+
+      - name: Run Ruff
+        run: python -m ruff check .
+
+      - name: Run mypy
+        run: python -m mypy .
+
+      - name: Run pytest
+        run: python -m pytest
+
+      - name: Verify import
+        run: python -c "import confident_extract"

confident_extract-0.1.0a1/.github/workflows/publish.yml

@@ -0,0 +1,33 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+permissions:
+  id-token: write
+  contents: read
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout repository
+        uses: actions/checkout@v4
+
+      - name: Set up Python
+        uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+
+      - name: Install build dependencies
+        run: |
+          python -m pip install --upgrade pip
+          pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - name: Publish package
+        uses: pypa/gh-action-pypi-publish@release/v1

confident_extract-0.1.0a1/.gitignore

@@ -0,0 +1,9 @@
+__pycache__/
+*.pyc
+.venv/
+.env
+.pytest_cache/
+.mypy_cache/
+dist/
+build/
+*.egg-info/

confident_extract-0.1.0a1/.pre-commit-config.yaml

@@ -0,0 +1,22 @@
+repos:
+  - repo: local
+    hooks:
+      - id: ruff-check
+        name: ruff check
+        entry: python -m ruff check .
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]
+      - id: ruff-format
+        name: ruff format
+        entry: python -m ruff format --check .
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]
+      - id: mypy
+        name: mypy
+        entry: python -m mypy .
+        language: system
+        pass_filenames: false
+        types_or: [python, pyi]
+

confident_extract-0.1.0a1/AGENTS.md

@@ -0,0 +1,40 @@
+# AGENTS.md
+
+## API Philosophy
+1. Every public function must have a clean, minimal call signature
+2. result = extract(text, schema=Invoice) is the gold standard
+3. Never chain abstraction layers: client.router.pipeline.manager.extract() is forbidden
+4. No required kwargs beyond text and schema on extract()
+
+## Performance Rules
+1. Always attempt orjson fast-path before any repair logic
+2. Validation overhead must stay under 10ms — benchmark every PR
+3. msgspec is the primary validator — Pydantic only in the optional bridge
+4. Never add blocking I/O inside the hot path
+5. Async variants must use asyncio natively, never run_in_executor() on sync code
+
+## Code Quality Rules
+1. Type hints required on every function signature, no exceptions
+2. Docstrings required on all public functions (Google style)
+3. ruff check . and mypy . must pass before any commit
+4. Unit test required for every new module — 90%+ coverage target
+5. No bare except clauses — always catch specific exception types
+
+## Dependency Rules
+1. Never introduce a new hard dependency without explicit approval
+2. Heavy dependencies (pydantic, openai, anthropic) are optional extras only
+3. No dependency on LangChain, LlamaIndex, or any agent framework
+4. If you need JSON parsing, use orjson — never stdlib json in hot paths
+
+## DO NOT BUILD
+1. Chatbot or agent framework
+2. Prompt template management
+3. Workflow / DAG orchestrator
+4. Vector store or retrieval system
+5. GUI, web interface, or dashboard
+
+## Security Rules
+1. No eval() or exec() on LLM output under any circumstances
+2. Sanitize all malformed inputs before processing
+3. Isolate provider integrations cleanly — no cross-contamination
+4. Deterministic parsing only — no hidden randomness in core pipeline

confident_extract-0.1.0a1/CHANGELOG.md

@@ -0,0 +1,23 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+The format is based on Keep a Changelog and the project follows semantic versioning pre-release tags for public alpha cuts.
+
+## [Unreleased]
+
+## [0.1.0a1] - 2026-05-12
+
+### Added
+
+- Sync public API at the package root: `extract`, `ExtractionResult`, `MsgspecValidationError`, and `ValidationError`
+- Deterministic preprocessing, repair, and `msgspec` validation layers
+- Minimal synchronous extraction pipeline with repair metadata and latency measurement
+- Unit coverage for preprocess, repair strategies, repair engine, validator adapter, extractor, and package-root API
+- Initial local benchmark suite for preprocess, repair, validation, and full extraction
+- Public alpha OSS release artifacts: README, contribution guide, changelog, and issue-template config
+
+### Changed
+
+- Package metadata updated for a public alpha release target
+- Development extras now include release tooling for `python -m build` and `twine check`

confident_extract-0.1.0a1/CONTRIBUTING.md

@@ -0,0 +1,73 @@
+# Contributing
+
+## Scope
+
+`confident-extract` is a narrow library for deterministic structured extraction from noisy JSON-like text.
+
+Before opening a change:
+
+- read [AGENTS.md](AGENTS.md)
+- keep the public API minimal
+- do not add provider logic, retries, or optional bridges unless the task explicitly requires them
+- avoid hidden fallbacks and blocking I/O in the hot path
+
+## Development setup
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+pre-commit install
+```
+
+## Quality gates
+
+Run these before opening a PR:
+
+```bash
+python -m ruff check .
+python -m mypy .
+python -m pytest
+```
+
+## Benchmarks
+
+Run the current local benchmark suite with:
+
+```bash
+python -m pytest benchmarks/test_extract_benchmarks.py
+python -m pytest benchmarks/test_extract_benchmarks.py --benchmark-sort=mean
+python -m pytest benchmarks/test_extract_benchmarks.py --benchmark-json /tmp/confident_extract_benchmarks.json
+```
+
+Notes:
+
+- benchmark numbers are local measurements unless explicitly captured from CI
+- do not make public performance claims from a single local run
+- if a change touches preprocessing, repair, validation, or extraction orchestration, rerun the benchmark suite
+
+## Release checks
+
+Before cutting a release candidate or alpha tag:
+
+```bash
+python -m build
+twine check dist/*
+```
+
+If `dist/` or `build/` already exists from a prior run, remove them and rebuild.
+
+## Pull requests
+
+Keep PRs narrow and traceable:
+
+- one feature area or one layer at a time
+- include tests for every changed module
+- explain behavior changes and benchmark impact when hot-path code changes
+
+## Issues
+
+Use GitHub issues for concrete bugs, regressions, or feature requests.
+
+For usage questions or local development setup, start from the README and this guide before filing an issue.

confident_extract-0.1.0a1/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 confident-extract 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.
+

confident_extract-0.1.0a1/PKG-INFO

@@ -0,0 +1,294 @@
+Metadata-Version: 2.4
+Name: confident-extract
+Version: 0.1.0a1
+Summary: Deterministic structured extraction from noisy JSON-like model output.
+Project-URL: Homepage, https://github.com/hitarthbuilds/confident-extract
+Project-URL: Repository, https://github.com/hitarthbuilds/confident-extract
+Project-URL: Issues, https://github.com/hitarthbuilds/confident-extract/issues
+Project-URL: Changelog, https://github.com/hitarthbuilds/confident-extract/blob/master/CHANGELOG.md
+Project-URL: CI, https://github.com/hitarthbuilds/confident-extract/actions/workflows/ci.yml
+Author: Hitarth Desai
+Maintainer: Hitarth Desai
+License: MIT
+License-File: LICENSE
+Keywords: json repair,llm,msgspec,orjson,schema validation,structured extraction
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: Implementation :: CPython
+Classifier: Topic :: Software Development :: Libraries :: Python Modules
+Classifier: Topic :: Text Processing
+Classifier: Typing :: Typed
+Requires-Python: >=3.11
+Requires-Dist: msgspec<1.0,>=0.18
+Requires-Dist: orjson<4.0,>=3.9
+Provides-Extra: anthropic
+Requires-Dist: anthropic<1.0,>=0.25; extra == 'anthropic'
+Provides-Extra: dev
+Requires-Dist: build<2.0,>=1.2; extra == 'dev'
+Requires-Dist: mypy<2.0,>=1.10; extra == 'dev'
+Requires-Dist: pre-commit<5.0,>=3.7; extra == 'dev'
+Requires-Dist: pytest-asyncio<1.0,>=0.23; extra == 'dev'
+Requires-Dist: pytest-benchmark<6.0,>=5.0; extra == 'dev'
+Requires-Dist: pytest<9.0,>=8.0; extra == 'dev'
+Requires-Dist: ruff<1.0,>=0.4; extra == 'dev'
+Requires-Dist: twine<7.0,>=5.1; extra == 'dev'
+Provides-Extra: ollama
+Requires-Dist: ollama<1.0,>=0.2; extra == 'ollama'
+Provides-Extra: openai
+Requires-Dist: openai<2.0,>=1.0; extra == 'openai'
+Provides-Extra: pydantic
+Requires-Dist: pydantic<3.0,>=2.0; extra == 'pydantic'
+Description-Content-Type: text/markdown
+
+# confident-extract
+
+[![CI](https://img.shields.io/github/actions/workflow/status/hitarthbuilds/confident-extract/ci.yml?branch=master&label=CI)](https://github.com/hitarthbuilds/confident-extract/actions/workflows/ci.yml)
+[![PyPI](https://img.shields.io/badge/PyPI-0.1.0a1%20pending-blue)](https://pypi.org/project/confident-extract/)
+[![Python](https://img.shields.io/badge/python-3.11%2B-blue)](https://pypi.org/project/confident-extract/)
+[![License](https://img.shields.io/github/license/hitarthbuilds/confident-extract)](https://github.com/hitarthbuilds/confident-extract/blob/master/LICENSE)
+
+`confident-extract` is a small Python library for deterministic structured extraction from noisy JSON-like model output.
+
+The current public alpha surface is synchronous and `msgspec`-first:
+
+- `from confident_extract import extract`
+- deterministic preprocessing and JSON repair
+- strict `msgspec.Struct` validation
+- lightweight result metadata around the validated output
+
+## Project overview
+
+The library is built for the common case where an upstream model or OCR system returns JSON-like text that is close to valid, but not always valid enough to parse or validate directly.
+
+The current sync pipeline is:
+
+1. preprocess raw text
+2. repair malformed JSON conservatively
+3. validate against a `msgspec.Struct` schema
+4. return a typed `ExtractionResult`
+
+The package does not currently include provider adapters, retries, async APIs, streaming, confidence scoring, or a pydantic bridge.
+
+## Install
+
+Install the published package:
+
+```bash
+python -m pip install confident-extract
+```
+
+Install for local development:
+
+```bash
+python -m pip install -e ".[dev]"
+```
+
+## Quickstart example
+
+```python
+import msgspec
+
+from confident_extract import extract
+
+
+class Invoice(msgspec.Struct):
+    invoice_id: int
+    status: str
+    total_cents: int
+
+
+result = extract(
+    text='{"invoice_id": 42, "status": "paid", "total_cents": 1999}',
+    schema=Invoice,
+)
+
+assert result.data == Invoice(invoice_id=42, status="paid", total_cents=1999)
+assert result.repair_applied is False
+```
+
+## Malformed JSON repair example
+
+```python
+import msgspec
+
+from confident_extract import extract
+
+
+class Invoice(msgspec.Struct):
+    invoice_id: int
+    status: str
+    total_cents: int
+
+
+raw = "{invoice_id: 42, status: 'paid', total_cents: 1999,}"
+result = extract(text=raw, schema=Invoice)
+
+assert result.data.status == "paid"
+assert result.repair_applied is True
+assert result.repaired_text == (
+    '{"invoice_id": 42, "status": "paid", "total_cents": 1999}'
+)
+```
+
+## Nested schema example
+
+```python
+import msgspec
+
+from confident_extract import extract
+
+
+class Contact(msgspec.Struct):
+    email: str
+    phone: str | None = None
+
+
+class Customer(msgspec.Struct):
+    name: str
+    contact: Contact
+
+
+class Invoice(msgspec.Struct):
+    invoice_id: int
+    customer: Customer
+    tags: list[str]
+
+
+raw = """
+{
+  "invoice_id": 7,
+  "customer": {
+    "name": "Acme",
+    "contact": {"email": "ops@example.com", "phone": "123"}
+  },
+  "tags": ["paid", "net30"]
+}
+"""
+
+result = extract(text=raw, schema=Invoice)
+
+assert result.data.customer.contact.email == "ops@example.com"
+assert result.data.tags == ["paid", "net30"]
+```
+
+## Benchmark snapshot
+
+Current local measurements were captured on May 12, 2026 with Python 3.13.5 using:
+
+```bash
+python -m pytest benchmarks/test_extract_benchmarks.py --benchmark-json /tmp/confident_extract_benchmarks.json
+```
+
+These are local measurements only. They are useful for regression tracking, not public performance claims.
+
+| Path | Scenario | p50 | p99 | Throughput |
+| --- | --- | ---: | ---: | ---: |
+| `preprocess()` | already-valid JSON | `2.17 us` | `2.46 us` | `462k ops/s` |
+| `preprocess()` | fenced ~10KB payload | `4.25 us` | `13.04 us` | `215k ops/s` |
+| `repair()` | valid fast path | `6.21 us` | `31.25 us` | `145k ops/s` |
+| `repair()` | trailing comma repair | `123.50 us` | `328.29 us` | `7.5k ops/s` |
+| `repair()` | multi-strategy repair | `611.38 us` | `965.96 us` | `1.7k ops/s` |
+| `validate_with_msgspec()` | nested decoded payload | `3.00 us` | `3.21 us` | `333k ops/s` |
+| `validate_with_msgspec()` | ~10KB decoded payload | `27.75 us` | `39.00 us` | `34.6k ops/s` |
+| `extract()` | valid fast path | `7.42 us` | `13.88 us` | `123k ops/s` |
+| `extract()` | trailing comma repair | `73.50 us` | `172.63 us` | `13.2k ops/s` |
+| `extract()` | multi-strategy nested repair | `406.83 us` | `820.83 us` | `2.2k ops/s` |
+| `extract()` | ~10KB nested payload | `92.83 us` | `167.75 us` | `10.5k ops/s` |
+| `extract()` | repeated ~10KB throughput | `94.69 us` | `96.21 us` | `10.6k ops/s` |
+
+### Benchmark caveats
+
+- The current suite is local, deterministic, and provider-free.
+- Outlier behavior will vary by machine, Python version, and thermal state.
+- The current repo does not yet publish benchmark baselines from CI runners.
+- Instructor, Guardrails, and LangChain comparisons are planned, but not yet implemented in this repository.
+
+### How to run benchmarks
+
+```bash
+python -m pytest benchmarks/test_extract_benchmarks.py
+python -m pytest benchmarks/test_extract_benchmarks.py --benchmark-sort=mean
+python -m pytest benchmarks/test_extract_benchmarks.py --benchmark-json /tmp/confident_extract_benchmarks.json
+```
+
+## Architecture flow diagram
+
+```text
+raw input text
+    |
+    v
+preprocess(text)
+    |
+    v
+repair(preprocessed_text)
+    |
+    v
+validate_with_msgspec(parsed payload, schema)
+    |
+    v
+ExtractionResult[T]
+  - data
+  - repair_applied
+  - repair_attempts
+  - raw_input
+  - repaired_text
+  - latency_ms
+```
+
+## Feature list
+
+- Minimal sync API: `extract(text, schema=Invoice)`
+- Conservative preprocessing for markdown fences, whitespace normalization, and escaped JSON
+- Deterministic JSON repair for trailing commas, unterminated containers, single quotes, and bare keys
+- Strict `msgspec.Struct` validation with field-path extraction on failures
+- Frozen, slotted extraction result contract
+- Package-root exports for the public sync API
+- Local benchmark coverage for preprocess, repair, validation, and full extraction
+
+## Roadmap
+
+- Stabilize the sync extraction API for `0.1.x`
+- Add the optional pydantic bridge outside the hot path
+- Add async and streaming APIs
+- Add provider adapters for live model integrations
+- Add confidence scoring and retry routing
+- Add reproducible cross-library benchmark comparisons
+
+## Contribution and dev setup
+
+`AGENTS.md` is the repo-level implementation contract. Read it before changing the code.
+
+Local setup:
+
+```bash
+python -m venv .venv
+source .venv/bin/activate
+python -m pip install --upgrade pip
+python -m pip install -e ".[dev]"
+pre-commit install
+```
+
+Quality gates:
+
+```bash
+python -m ruff check .
+python -m mypy .
+python -m pytest
+```
+
+Benchmark and release checks:
+
+```bash
+python -m pytest benchmarks/test_extract_benchmarks.py
+python -m build
+twine check dist/*
+```
+
+For contributor expectations, issue filing guidance, and release checks, see [CONTRIBUTING.md](https://github.com/hitarthbuilds/confident-extract/blob/master/CONTRIBUTING.md).