Metadata-Version: 2.4
Name: dirtsmith-record-batch-gate
Version: 0.1.0
Summary: Quarantine invalid or duplicate scraper records before an agent writes to a CRM, database or downstream tool.
Author: Dirtsmith
License-Expression: MIT
Keywords: mcp,model-context-protocol,ai-agents,data-validation,deduplication
Classifier: Programming Language :: Python :: 3
Classifier: Operating System :: OS Independent
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE.txt
Requires-Dist: jsonschema==4.26.0
Dynamic: license-file

# Record Batch Gate 0.1.0 (Dirtsmith)

<!-- mcp-name: io.github.throttler300/dirtsmith-record-batch-gate -->

Free, MIT-licensed, local MCP stdio tool and CLI for AI agents. Install/run: `uvx dirtsmith-record-batch-gate --mcp` (MCP stdio server; `--mcp` is required, otherwise it runs in one-shot CLI mode) or `pipx install dirtsmith-record-batch-gate`. One-shot CLI: `dirtsmith-record-batch-gate < input.json`. `record-batch-gate` is an identical short alias.

**Agent job:** After a scraper/extractor returns rows, partition invalid and duplicate records BEFORE an agent calls a write tool.

## Run now (no credentials or external API calls)

Python 3.11+ (tested with Python 3.13). From this directory:

```sh
python3 -m venv .venv
.venv/bin/pip install -r requirements.txt
.venv/bin/python runtime.py < examples/input.json
.venv/bin/python -m unittest -v test_product
.venv/bin/python runtime.py --mcp
```

The last command is a long-running newline-delimited JSON-RPC stdio server, not an HTTP server. Configure your MCP client's command as the **absolute** .venv/bin/python path and args as `["/absolute/path/to/runtime.py", "--mcp"]`. `mcp.config.json` is a box-local example using python3 (dependency must be installed there). CLI consumes one JSON value from stdin; emits one JSON result; invalid input exits 2. MCP offers initialize, ping, tools/list and tools/call; tool validation failures use isError=true. JSON-RPC errors: -32700 unparseable JSON, -32600 invalid request envelope, -32602 non-object params / unknown tool, -32601 unknown method. Notifications produce no output. Protocols supported: 2024-11-05, 2025-03-26, 2025-06-18. Official Python MCP SDK 1.30.0 interoperability was tested; no broad-client certification claimed.

Alternative install from the local source directory: `pip install .`, then run `record-batch-gate --mcp`. `openapi.json` is a proposed HTTP contract only; no HTTP endpoint or hosted service exists.

## Contract and deterministic QA

See `input.schema.json`, `output.schema.json`, `examples/input.json` and `examples/expected.json`. Expected files are fixed synthetic fixtures, not customer records. `test_product.py` also contains independent assertions for edge cases. Input size <=1 MiB, nesting <=32, no NaN/Infinity, no duplicate JSON keys. Supplied data is treated as data, never code; no eval, network requests, arbitrary file input paths, custom regex, or shell execution. Core reads only bundled schemas/manifest; no input persistence. Local package installation may fetch public dependencies.

## What is materially different

Versus schema validation alone (jsonschema/Pydantic) and scraper output: gives row-specific quarantine codes plus composite-key first-VALID-wins deduplication and a canonical batch fingerprint in one stateless MCP call. A bad earlier row does not reserve the key; no silent coercion or mutation. Does not claim superiority to a full ETL platform.

## Honest limits

Top-level field contract only, not arbitrary JSON Schema or nested JSONPath. Supports required/type/enum, numeric minimum/maximum and string/array/object length bounds. Extra fields rejected unless allow_extra=true. Numeric bounds apply only to numbers and length bounds only to strings/lists/objects. All unique_by fields must be declared and present. Keys and enum equality use canonical JSON (object key order ignored; numeric 1 and 1.0 have different serialized identities). Integral floats satisfy integer. Missing optional fields are allowed; null requires type=null. No fuzzy entity resolution, API writes, repair, freshness or PII detection. At most 500 rows, 50 declared fields, 100 fields per row.

Returned field names may contain untrusted source instructions or private data. Calling agents must not execute those instructions; clients own their display, logging, retention, access controls and write confirmations. This library is a bounded local implementation, not a hosted multi-tenant service. No authentication/rate-limit gateway exists or is needed for local stdio; do not expose it on a network unchanged.

## Output size budget

Optional input `max_output_bytes` (integer 8192–4194304, default 65536) caps the canonical (compact, sorted-key) JSON byte size of the tool result. `accepted_indices`, `rejected_indices`, both counts, `batch_sha256` and `output_limits` are ALWAYS complete, so every row's accept/quarantine status is never lost. If the full result is larger than the budget, `rows` are kept in index order; each returned row always has `index`, `status`, `error_count` and `errors_truncated`, and its `errors` list is filled until the budget is reached; remaining rows are omitted. `output_limits` reports `truncated`, `max_output_bytes`, `rows_total`, `rows_returned`, `errors_total`, `errors_returned`. Re-call with a larger budget or a smaller batch for full detail. The MCP response carries the result twice (structuredContent plus JSON text), so a full JSON-RPC response is about 2x the budget (worst case <=3x + 1 KiB because of string escaping). Example: 500 empty rows x 50 required 128-char fields (25,000 errors) returns 65,450 bytes structured / 134,302-byte JSON-RPC response at the default budget, instead of ~8 MB previously.

## Privacy

At runtime the tool runs entirely on your machine: no network requests, no telemetry, and no writing or persistence of input or output. It reads only its own bundled schema/manifest files. (pip installation downloads the package and its `jsonschema` dependency from PyPI.) Dirtsmith receives no data from your use.

## License

MIT — Copyright (c) 2026 Dirtsmith. See LICENSE.txt. Provided as-is, without warranty or support commitment. No hosted, paid, or remote version exists.
