agent-json-reliability 0.1.0__py3-none-any.whl

agent_json_reliability-0.1.0.dist-info/METADATA

@@ -0,0 +1,128 @@
+Metadata-Version: 2.4
+Name: agent-json-reliability
+Version: 0.1.0
+Summary: Deterministic JSON repair and JSON Schema validation for AI agents and software. No LLM required.
+Author: Agent JSON Reliability contributors
+License: MIT
+Project-URL: Homepage, https://github.com/toninovo4249-ai/agent-json-reliability
+Keywords: json,json-schema,json-repair,ai-agents,mcp,structured-output
+Classifier: Development Status :: 4 - Beta
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Software Development :: Libraries
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: fastapi>=0.115.0
+Requires-Dist: uvicorn>=0.30.0
+Requires-Dist: jsonschema>=4.23.0
+Dynamic: license-file
+
+# Agent JSON Reliability
+
+STATUS=BETA version `0.1.0`
+
+AI agents and software frequently emit malformed JSON: markdown fences, trailing commas, single quotes, `True`/`False`/`None`, and extra prose around one object.
+
+**Agent JSON Reliability** is a deterministic pipeline for that failure mode:
+
+1. **inspect** — diagnose whether the text is JSON and which failures are present
+2. **safe repair** — apply only structural, unambiguous fixes
+3. **validate** — optional JSON Schema check on the result
+4. **structured diagnostics** — `valid_original`, `repaired`, `valid_final`, `schema_valid`, `unsafe_or_ambiguous`, `changes`, `errors`
+
+This is not a generic jsonschema wrapper. The primary value is turning **malformed agent output** into reliable structured data **without an LLM** and **without inventing semantic values**.
+
+When repair would require guessing (truncated objects, missing values, competing JSON documents), the service **refuses**. That is correct behavior.
+
+Primary HTTP endpoint: `POST /v1/json/reliable`
+
+MCP tools (same core functions, no duplicate implementation): `json_reliable` / `reliable_json`, `validate_json`, `repair_json`, `inspect_json`
+
+<!-- mcp-name: io.github.toninovo4249-ai/agent-json-reliability -->
+
+## Before / after (safe repair)
+
+Malformed agent output:
+
+```json
+{
+  "text": "```json\n{\"name\":\"alice\",\"age\":30,}\n```"
+}
+```
+
+Expected result (semantically equivalent valid JSON):
+
+- `valid_original=false`
+- `repaired=true`
+- `valid_final=true`
+- `unsafe_or_ambiguous=false`
+- `json` → `{"name":"alice","age":30}`
+
+If a schema is supplied and satisfied: `schema_valid=true`.
+
+## Safe refusal (ambiguous)
+
+Truncated input such as `{"user":` is JSON-intended but not deterministically repairable without inventing keys or values.
+
+Expected:
+
+- HTTP `200` (documented safe response)
+- `valid_final=false`
+- `unsafe_or_ambiguous=true` **or** `repaired=false`
+
+Do not treat a correct refusal as a product failure.
+
+## Run locally (no Hunter)
+
+```bash
+python -m pip install -r requirements.txt
+python serve.py
+```
+
+Binds `127.0.0.1:8770` by default. Set `PUBLIC_BASE_URL` to an HTTPS origin only when you expose the process yourself. Do not commit a temporary tunnel hostname as the canonical URL.
+
+## HTTP examples
+
+See `examples/curl.md`, `examples/python.py`, `examples/javascript.js`.
+
+Remote examples use `${PUBLIC_BASE_URL}`. Local default is `http://127.0.0.1:8770`.
+
+Share URLs (optional, unverified telemetry tags):
+
+- `/?source=github`
+- `/?source=mcp-registry`
+- `/?source=api-directory`
+
+## MCP (stdio — durable)
+
+Package transport does not depend on a temporary public URL.
+
+```json
+{
+  "mcpServers": {
+    "agent-json-reliability": {
+      "command": "python",
+      "args": ["-m", "products.gateway.mcp_stdio"]
+    }
+  }
+}
+```
+
+After you publish to PyPI (free): `uvx agent-json-reliability`.
+
+Remote HTTP MCP (`POST /mcp`) is for a running instance. Prefer stdio/package for Official MCP Registry metadata.
+
+## Machine discovery
+
+- `GET /.well-known/agent-services.json`
+- `GET /openapi.json`
+- `GET /llms.txt`
+- `GET /AGENTS.md`
+- `POST /mcp` JSON-RPC (`tools/list`, `tools/call`)
+
+## What this package does not include
+
+No Hunter market database, no private reports, no Windows user paths, no collectors, no wallets, no x402 payment.
+
+Free beta: no auth, no payment.

agent_json_reliability-0.1.0.dist-info/RECORD

@@ -0,0 +1,30 @@
+serve.py,sha256=q5a-jhErzovqZ-XGMRrUV8Eepy5SNJ0WfmFQaJZmBWo,958
+agent_json_reliability-0.1.0.dist-info/licenses/LICENSE,sha256=3dC8g3pbUlohK3QJEGaAn12Qg30ciDaELSTd0BXIuGE,516
+products/__init__.py,sha256=HuOKG1roMpOoMIYohAffe21pBS3DEVoTt4mF4nmSMEo,70
+products/agent_json_reliability/__init__.py,sha256=wMoZTPy4uhabZCyc4xe0qX_6Q17qvU4zlG4CHtjfh0Q,298
+products/agent_json_reliability/inspect.py,sha256=LcymxHNKlv-H6gxyovl_yhwva8QJDUW6El75nBSWnBc,2196
+products/agent_json_reliability/reliable.py,sha256=8gGopZG6EMW3hGgWh_QOBRVzMWAPVc7LjVhR0Ui5Q4M,2592
+products/agent_json_reliability/repair.py,sha256=P1XTciJbVlqYmcwYJCZ6vyCYHZ9od91MdLInoUI8Oi0,7395
+products/agent_json_reliability/validate.py,sha256=ffBiHE6leHlGqTWXVunD2qSjeVsCsmBOSF3c7LN4VAU,7030
+products/beta/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+products/beta/app.py,sha256=rhJ7m-l_0CaVnyEknfDL_ZI2VQB1puC0SLCG3bhMksA,12702
+products/beta/batch.py,sha256=Lg3ZKxOcENZyJMKv0NQlGNF_MxWjbEVlzzTEOg3doAI,917
+products/beta/catalog.py,sha256=94Gmxi-HQHjBcn1WX1aB8VFxNNAVDmctMuKjJf2sdow,2080
+products/beta/identity.py,sha256=ouXpqNQ4pjcBhzc9dYk6znBUe2y4pO7mSLQzmKwZGl8,4343
+products/beta/landing.py,sha256=EReK7hINodUIPPe-Y2ixEfizXA48JUrgekZTc_Gfbkc,4669
+products/beta/security.py,sha256=6YJbw4ahcR_G8n1pq04ndS3gP9AeWunaZRfxJQphdvc,2597
+products/beta/selfcheck.py,sha256=G_iF5LqAReqLyKImScXurc5Ud99zmGfUcCyqCL5AqhU,1011
+products/beta/settings.py,sha256=W6yfqC2yyj_-xulhPF3Ery8tO8f5ChlpuAUVvzF9h6U,2973
+products/beta/store.py,sha256=kLwTrL-iNFG2pLyML8ApTWDJyYdfU-U0sW7YnLvwcSE,4732
+products/common/__init__.py,sha256=rJlpYCJdYduuCGz_7RftJexTnJF3WrdekL4yzG1glko,175
+products/common/timing.py,sha256=8F3x3x7n5jrp1e-l2SEjWaOPq9FOCREkipJINnf7Wv0,313
+products/gateway/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+products/gateway/manifest.py,sha256=sDFQsA71EKrF4sFrSS98oe5IpsTEQiLm7hBUCqf1isc,6993
+products/gateway/mcp_server.py,sha256=YmSLbjr9D6Ej8YubSPj0aOKjHqlnjqM1QmZj_4vVKis,2732
+products/gateway/mcp_stdio.py,sha256=B0japGfz3QKOgYrfNXtj-wXWcoUKrW6OFjlLAlylh3I,1508
+products/gateway/rate_limit.py,sha256=LwcIyqk7BWTxAaJWhm5uTrXaWo1AOD_WYbpNSRGADsg,885
+agent_json_reliability-0.1.0.dist-info/METADATA,sha256=V4eMP8eTvNfaqV4Fith5UUaksZE8N_omc8aGVeQtxZI,4252
+agent_json_reliability-0.1.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+agent_json_reliability-0.1.0.dist-info/entry_points.txt,sha256=nr7RzsB4dHKHEQjtA1M1ieHro5HRfdOwTlNTwUxrS0M,117
+agent_json_reliability-0.1.0.dist-info/top_level.txt,sha256=WdV6O4or29KOsiwfII1hnZH5pdU0DnRVfpa1hp1Vdtc,15
+agent_json_reliability-0.1.0.dist-info/RECORD,,

agent_json_reliability-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

agent_json_reliability-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,3 @@
+[console_scripts]
+agent-json-reliability = products.gateway.mcp_stdio:main
+agent-json-reliability-serve = serve:main

agent_json_reliability-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,5 @@
+MIT License
+
+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 SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND.

agent_json_reliability-0.1.0.dist-info/top_level.txt

@@ -0,0 +1,2 @@
+products
+serve

products/__init__.py

@@ -0,0 +1 @@
+"""Local zero-cost product prototypes. Independent of collectors."""

products/agent_json_reliability/__init__.py

@@ -0,0 +1,7 @@
+from __future__ import annotations
+
+from products.agent_json_reliability.inspect import inspect_json
+from products.agent_json_reliability.repair import repair_json
+from products.agent_json_reliability.validate import validate_json
+
+__all__ = ["validate_json", "repair_json", "inspect_json"]

products/agent_json_reliability/inspect.py

@@ -0,0 +1,62 @@
+from __future__ import annotations
+
+import json
+import re
+from typing import Any
+
+from products.agent_json_reliability.repair import repair_json
+from products.common.timing import Clock
+
+_FAILURES = [
+    ("markdown_fence", re.compile(r"```")),
+    ("trailing_comma", re.compile(r",\s*[}\]]")),
+    ("single_quotes", re.compile(r"'")),
+    ("python_literals", re.compile(r"\b(True|False|None)\b")),
+    ("comments", re.compile(r"//|/\*")),
+    ("leading_prose", None),
+    ("truncated", None),
+]
+
+
+def inspect_json(text: str) -> dict[str, Any]:
+    with Clock() as sw:
+        if not isinstance(text, str):
+            text = str(text)
+        raw = text.strip()
+        valid = False
+        err_pos = None
+        try:
+            json.loads(raw)
+            valid = True
+        except json.JSONDecodeError as e:
+            err_pos = e.pos
+        types: list[str] = []
+        if re.search(r"```", raw):
+            types.append("markdown_fence")
+        if re.search(r",\s*[}\]]", raw):
+            types.append("trailing_comma")
+        if "'" in raw and '"' not in raw:
+            types.append("single_quotes")
+        if re.search(r"\b(True|False|None)\b", raw):
+            types.append("python_literals")
+        if "//" in raw or "/*" in raw:
+            types.append("comments")
+        stripped = raw.lstrip()
+        if stripped and stripped[0] not in "{[":
+            types.append("leading_prose")
+        if raw.count("{") > raw.count("}") or raw.count("[") > raw.count("]"):
+            types.append("truncated")
+        if re.search(r"\}\s*\{", raw):
+            types.append("multiple_objects")
+        likely = valid or bool(re.search(r"[\{\[]", raw))
+        rep = repair_json(raw)
+        complexity = min(100, raw.count("{") + raw.count("[") + raw.count(":") + len(raw) // 200)
+        return {
+            "valid_json": valid,
+            "likely_json": likely,
+            "error_position": err_pos,
+            "detected_failure_types": types,
+            "repair_possible": bool(rep.get("repaired") or valid),
+            "estimated_complexity": complexity,
+            "processing_ms": sw.ms,
+        }

products/agent_json_reliability/reliable.py

@@ -0,0 +1,66 @@
+from __future__ import annotations
+
+from typing import Any
+
+from products.agent_json_reliability.inspect import inspect_json
+from products.agent_json_reliability.repair import repair_json
+from products.agent_json_reliability.validate import validate_json
+from products.common.timing import Clock
+
+
+def reliable_json(text: str, schema: dict | None = None, mode: str = "safe") -> dict[str, Any]:
+    """inspect → safe repair if needed → optional schema validate. Same primitives as HTTP tools."""
+    with Clock() as sw:
+        insp = inspect_json(text)
+        valid_original = bool(insp.get("valid_json"))
+        changes: list[str] = []
+        repaired = False
+        payload: Any = None
+        unsafe = False
+        if valid_original:
+            import json
+
+            payload = json.loads(text.strip().lstrip("\ufeff"))
+        else:
+            rep = repair_json(text, mode)
+            repaired = bool(rep.get("repaired"))
+            payload = rep.get("json")
+            changes = list(rep.get("changes") or [])
+            unsafe = bool(rep.get("unsafe_or_ambiguous"))
+        valid_final = payload is not None
+        schema_valid = None
+        errors: list = []
+        if valid_final and schema is not None:
+            v = validate_json(payload, schema)
+            schema_valid = v.get("schema_valid")
+            errors = v.get("errors") or []
+            valid_final = bool(schema_valid)
+        elif not valid_final:
+            errors = [{"message": "unrepaired_or_invalid"}]
+        return {
+            "valid_original": valid_original,
+            "repaired": repaired,
+            "json": payload,
+            "valid_final": valid_final and payload is not None and (schema_valid is not False),
+            "schema_valid": schema_valid,
+            "unsafe_or_ambiguous": unsafe,
+            "changes": changes,
+            "errors": errors,
+            "inspect": insp,
+            "processing_ms": sw.ms,
+            "outcome_class": _outcome(valid_original, repaired, payload, schema_valid, errors),
+        }
+
+
+def _outcome(valid_original, repaired, payload, schema_valid, errors) -> str:
+    if schema_valid is False:
+        return "SCHEMA_INVALID"
+    if schema_valid is True:
+        return "SCHEMA_VALID"
+    if valid_original:
+        return "ORIGINAL_VALID"
+    if repaired and payload is not None:
+        return "SAFE_REPAIR_SUCCESS"
+    if any((e.get("message") or "").startswith("schema") for e in errors or []):
+        return "INVALID_SCHEMA"
+    return "SAFE_REPAIR_REFUSED"

products/agent_json_reliability/repair.py

@@ -0,0 +1,237 @@
+from __future__ import annotations
+
+import ast
+import json
+import re
+from typing import Any
+
+from products.common.timing import Clock
+
+_FENCE = re.compile(r"```(?:json|JSON)?\s*([\s\S]*?)```", re.MULTILINE)
+_TRAIL_COMMA = re.compile(r",(\s*[}\]])")
+_COMMENT_LINE = re.compile(r"(^|[^:])//.*?$", re.MULTILINE)
+_COMMENT_BLOCK = re.compile(r"/\*[\s\S]*?\*/")
+
+
+def _extract_fenced(text: str, changes: list[str]) -> str:
+    m = _FENCE.search(text)
+    if m:
+        changes.append("strip_markdown_fence")
+        return m.group(1).strip()
+    return text
+
+
+def _extract_balanced(text: str, changes: list[str]) -> str:
+    starts = [i for i, ch in enumerate(text) if ch in "{["]
+    if not starts:
+        return text.strip()
+    first = starts[0]
+    chunk = text[first:]
+    if first > 0 and text[:first].strip():
+        changes.append("strip_leading_prose")
+    depth_obj = depth_arr = 0
+    in_str = False
+    esc = False
+    last = -1
+    for i, ch in enumerate(chunk):
+        if in_str:
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+            continue
+        if ch == '"':
+            in_str = True
+            continue
+        if ch == "{":
+            depth_obj += 1
+        elif ch == "}":
+            depth_obj -= 1
+        elif ch == "[":
+            depth_arr += 1
+        elif ch == "]":
+            depth_arr -= 1
+        if depth_obj == 0 and depth_arr == 0 and ch in "}]":
+            last = i
+            break
+    if last >= 0:
+        tail = chunk[last + 1 :]
+        st = tail.strip()
+        if st.startswith("{") or st.startswith("["):
+            changes.append("multiple_json_values")
+            return chunk
+        if st:
+            changes.append("strip_trailing_prose")
+        return chunk[: last + 1]
+    return chunk
+
+
+def _strip_comments(text: str, changes: list[str]) -> str:
+    if "//" not in text and "/*" not in text:
+        return text
+    nxt = _COMMENT_BLOCK.sub("", text)
+    nxt = _COMMENT_LINE.sub(lambda m: m.group(1), nxt)
+    if nxt != text:
+        changes.append("strip_comments")
+    return nxt
+
+
+def _py_literals(text: str, changes: list[str]) -> str:
+    nxt = re.sub(r"\bTrue\b", "true", text)
+    nxt = re.sub(r"\bFalse\b", "false", nxt)
+    nxt = re.sub(r"\bNone\b", "null", nxt)
+    if nxt != text:
+        changes.append("python_literals")
+    return nxt
+
+
+def _trailing_commas(text: str, changes: list[str]) -> str:
+    nxt, n = _TRAIL_COMMA.subn(r"\1", text)
+    if n:
+        changes.append("strip_trailing_commas")
+    return nxt
+
+
+def _close_truncated(text: str, changes: list[str]) -> str | None:
+    """Close extra { [ only when the remainder is empty of required values."""
+    in_str = False
+    esc = False
+    stack: list[str] = []
+    last_sig = ""
+    for ch in text:
+        if in_str:
+            if esc:
+                esc = False
+            elif ch == "\\":
+                esc = True
+            elif ch == '"':
+                in_str = False
+            continue
+        if ch == '"':
+            in_str = True
+            last_sig = '"'
+            continue
+        if ch in "{[":
+            stack.append("}" if ch == "{" else "]")
+            last_sig = ch
+        elif ch in "}]":
+            if not stack or stack[-1] != ch:
+                return None
+            stack.pop()
+            last_sig = ch
+        elif ch == ":":
+            last_sig = ":"
+        elif ch == ",":
+            last_sig = ","
+        elif not ch.isspace():
+            last_sig = "v"
+    if in_str:
+        return None
+    if not stack:
+        return None
+    if last_sig in {":"}:
+        return None  # would invent a value
+    closed = text + "".join(reversed(stack))
+    changes.append("close_truncated_brackets")
+    return closed
+
+
+def _try_load(text: str) -> Any:
+    return json.loads(text)
+
+
+def _literal_eval_jsonish(text: str) -> Any | None:
+    try:
+        val = ast.literal_eval(text)
+    except (SyntaxError, ValueError, MemoryError):
+        return None
+    if isinstance(val, (dict, list, str, int, float, bool)) or val is None:
+        return val
+    return None
+
+
+def repair_json(text: str, mode: str = "safe") -> dict[str, Any]:
+    with Clock() as sw:
+        changes: list[str] = []
+        if not isinstance(text, str):
+            return _fail(sw, "text_not_string", changes)
+        if len(text.encode("utf-8")) > 262_144:
+            return _fail(sw, "too_large", changes)
+        raw = text.strip().lstrip("\ufeff")
+        if raw != text.strip() or text[:1] == "\ufeff" or text != text.strip():
+            changes.append("strip_bom_or_whitespace")
+        if not raw:
+            return _fail(sw, "empty", changes)
+
+        try:
+            parsed = _try_load(raw)
+            return _ok(parsed, bool(changes), changes, "high", False, sw)
+        except json.JSONDecodeError:
+            pass
+
+        work = _extract_fenced(raw, changes)
+        work = _extract_balanced(work, changes)
+        if "multiple_json_values" in changes:
+            return _fail(sw, "multiple_json_values", changes, unsafe=True)
+        work = _strip_comments(work, changes)
+
+        looks_py = ("True" in work or "False" in work or "None" in work or ("'" in work and '"' not in work))
+        if looks_py:
+            lit = _literal_eval_jsonish(work)
+            if lit is not None:
+                changes.append("python_literal_eval")
+                return _ok(lit, True, changes, "medium", False, sw)
+
+        work = _py_literals(work, changes)
+        work = _trailing_commas(work, changes)
+
+        try:
+            parsed = _try_load(work)
+            return _ok(parsed, True, changes, "high", False, sw)
+        except json.JSONDecodeError:
+            pass
+
+        closed = _close_truncated(work, changes)
+        if closed is not None:
+            closed = _trailing_commas(closed, changes)
+            try:
+                parsed = _try_load(closed)
+                return _ok(parsed, True, changes, "medium", False, sw)
+            except json.JSONDecodeError:
+                changes[:] = [c for c in changes if c != "close_truncated_brackets"]
+
+        decoder = json.JSONDecoder()
+        try:
+            first, idx = decoder.raw_decode(work)
+            rest = work[idx:].strip()
+            if rest:
+                return _fail(sw, "multiple_json_values", changes, unsafe=True)
+            return _ok(first, True, changes, "medium", False, sw)
+        except json.JSONDecodeError:
+            pass
+
+        return _fail(sw, "unambiguous_repair_impossible", changes, unsafe=True)
+
+
+def _ok(parsed, repaired, changes, confidence, unsafe, sw):
+    return {
+        "repaired": repaired,
+        "json": parsed,
+        "changes": changes,
+        "confidence": confidence,
+        "unsafe_or_ambiguous": unsafe,
+        "processing_ms": sw.ms,
+    }
+
+
+def _fail(sw, reason: str, changes: list[str], unsafe: bool = False):
+    return {
+        "repaired": False,
+        "json": None,
+        "changes": changes + [reason],
+        "confidence": "low",
+        "unsafe_or_ambiguous": True if unsafe else False,
+        "processing_ms": sw.ms,
+    }