delegation_output_schema.py 5.2 KB

123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596979899100101102103104105106107108109110111112113114115
  1. """Structured-output schema helpers for delegate_task.
  2. Optional per-task ``output_schema`` (a JSON Schema object): the child gets an
  3. OUTPUT CONTRACT block appended to its context, the parent validates the final
  4. answer with jsonschema, and on failure sends exactly ONE bounded retry turn
  5. carrying the validation errors verbatim (more retries make frontier models
  6. drop fields that were right the first time; the schema is never re-pasted).
  7. """
  8. from __future__ import annotations
  9. import json
  10. import logging
  11. from typing import Any, Dict, List, Optional, Tuple
  12. logger = logging.getLogger(__name__)
  13. def coerce_output_schema(raw: Any) -> tuple[Optional[dict[str, Any]], Optional[str]]:
  14. """``(schema, None)`` when usable, ``(None, error)`` when not; ``None`` input
  15. passes through as ``(None, None)`` (no schema requested)."""
  16. if raw is None:
  17. return None, None
  18. if isinstance(raw, str):
  19. # Models sometimes double-encode the schema as a JSON string.
  20. try:
  21. raw = json.loads(raw)
  22. except (ValueError, TypeError):
  23. return None, "output_schema must be a JSON Schema object, got a non-JSON string."
  24. if not isinstance(raw, dict):
  25. return None, "output_schema must be a JSON Schema object."
  26. if not isinstance(raw, dict):
  27. return None, f"output_schema must be a JSON Schema object, got {type(raw).__name__}."
  28. try:
  29. from jsonschema.validators import validator_for # type: ignore[import-untyped]
  30. validator_for(raw).check_schema(raw)
  31. except ImportError:
  32. # Degrade to accepting the dict as-is so delegation still works without jsonschema.
  33. logger.debug("jsonschema unavailable; skipping output_schema meta-validation")
  34. except Exception as exc:
  35. return None, f"output_schema is not a valid JSON Schema: {exc}"
  36. return raw, None
  37. def append_output_contract(context: Optional[str], schema: dict[str, Any]) -> str:
  38. """Append the explicit output contract block to a child's context."""
  39. try:
  40. schema_text = json.dumps(schema, indent=2, ensure_ascii=False)
  41. except (TypeError, ValueError):
  42. schema_text = str(schema)
  43. block = ("OUTPUT CONTRACT (machine-validated):\n"
  44. "Your FINAL response must be ONLY the JSON value that validates against this JSON "
  45. "Schema — no prose before or after it, no code fence, no explanation. Anything else "
  46. "costs a correction turn and, if it fails again, is handed to the caller unvalidated.\n"
  47. f"{schema_text}")
  48. base = (context or "").rstrip()
  49. return f"{base}\n\n{block}" if base else block
  50. def extract_json_candidate(text: str) -> str:
  51. """Strip markdown fences and prose around the outermost ``{...}``/``[...]``."""
  52. raw = (text or "").strip()
  53. if raw.startswith("```"):
  54. raw = raw.split("\n", 1)[-1]
  55. if raw.rstrip().endswith("```"):
  56. raw = raw.rstrip()[: -3]
  57. raw = raw.strip()
  58. if raw.lower().startswith("json\n"):
  59. raw = raw.split("\n", 1)[1]
  60. # Try each bracket kind's outermost span, earliest opener first, and keep the first that parses:
  61. # checking "{" before "[" unconditionally sliced a fenced array down to its first..last object and
  62. # rejected every valid array answer.
  63. spans = []
  64. for opener, closer in (("{", "}"), ("[", "]")):
  65. start, end = raw.find(opener), raw.rfind(closer)
  66. if start >= 0 and end > start:
  67. spans.append((start, raw[start : end + 1]))
  68. for _start, candidate in sorted(spans):
  69. try:
  70. json.loads(candidate)
  71. return candidate
  72. except ValueError:
  73. continue
  74. return spans[0][1] if spans else raw
  75. def validate_output(text: str, schema: dict[str, Any]) -> tuple[bool, list[str]]:
  76. """``(True, [])`` or ``(False, errors)`` with strings suitable for the retry turn."""
  77. candidate = extract_json_candidate(text or "")
  78. if not candidate.strip():
  79. return False, ["Response was empty — expected a JSON object matching the schema."]
  80. try:
  81. parsed = json.loads(candidate)
  82. except (ValueError, TypeError) as exc:
  83. return False, [f"Response is not valid JSON: {exc}"]
  84. try:
  85. from jsonschema.validators import validator_for # type: ignore[import-untyped]
  86. except ImportError:
  87. logger.debug("jsonschema unavailable; accepting parsed JSON without validation")
  88. return True, []
  89. validator = validator_for(schema)(schema)
  90. errors = sorted(validator.iter_errors(parsed), key=lambda e: list(e.absolute_path))
  91. rendered = [ # bound error volume for the retry prompt
  92. "$" + "".join(f"[{p}]" if isinstance(p, int) else f".{p}" for p in err.absolute_path) + f": {err.message}"
  93. for err in errors[:10]]
  94. return not rendered, rendered
  95. def build_retry_message(errors: list[str]) -> str:
  96. """Single bounded retry turn: errors verbatim, schema deliberately NOT re-pasted."""
  97. error_block = "\n".join(f"- {e}" for e in errors)
  98. return ("Your previous final response was rejected by the output contract "
  99. "validator. Validation errors:\n" f"{error_block}\n\n"
  100. "Reply with ONLY the corrected JSON object matching the OUTPUT "
  101. "CONTRACT schema from your task context. No prose, no explanations.")