feat(ai): llm structured output retry and json schema repair engine (#123)

[dan-petty]

Resolves #123. Implements automated structured output and JSON schema repair pipeline with reflection retry loop in devops_cli.ai.client.

[Copilot]

🟡 Changes recommended

A critical configuration cleanup causes production import failures, alongside unresolved structured-output safety and validation issues.

Get a fresh assessment by requesting another Copilot review.

Pull request overview

Adds structured LLM output parsing, JSON repair, schema validation, and reflection retries to LLMClient.

Changes:

• Adds StructuredOutputMixin and structured-output tests.
• Integrates repair, validation, retries, and telemetry.
• Updates configuration constants, defaults, exports, and task metadata.

File summaries

File	Summary
tests/test_ai_client_structured.py	Structured-output tests
src/devops_cli/config/settings.py	Configuration reference updates
src/devops_cli/config/defaults.py	Retry defaults and legacy cleanup
src/devops_cli/config/constants.py	Structured-output constants
src/devops_cli/config/__init__.py	Configuration exports
src/devops_cli/ai/client/unified.py	Structured-output mixin integration
src/devops_cli/ai/client/structured.py	Parsing, repair, validation, and retry engine
src/devops_cli/ai/client/__init__.py	Public client exports
docs/agent/tasks/task-123-llm-structured-output-retry-json-repair.md	Task scope and status metadata

Review details

Suppressed comments (4)

src/devops_cli/ai/client/structured.py:90

• Pydantic models ignore unknown fields by default, so payloads containing unexpected schema keys are accepted and silently discarded here. That means the engine does not detect one of the malformed-output cases described by issue #123; enforce the schema's extra-field policy (or explicitly reject extras) before returning the model.

    try:
        if hasattr(schema, "model_validate"):
            return schema.model_validate(json_data), None
        return TypeAdapter(schema).validate_python(json_data), None

src/devops_cli/ai/client/structured.py:73

• This sends the entire unbounded model response through json_repair and then appends the entire raw response to the next retry prompt. A large provider response can therefore cause excessive CPU, memory, and prompt-token usage across retries; apply the existing bounded JSON-repair limit (or an equivalent structured-output cap) before repair and reflection.

    try:
        repaired = json_repair.loads(candidate)
        if repaired != "" and repaired is not None and isinstance(repaired, (dict, list)):
            return repaired, True, None
        repaired_full = json_repair.loads(cleaned)
        if (
            repaired_full != ""
            and repaired_full is not None
            and isinstance(repaired_full, (dict, list))
        ):
            return repaired_full, True, None

src/devops_cli/ai/client/structured.py:225

• max_retries is accepted without an upper bound, so callers can request arbitrarily many model calls even though issue #123's contract caps structured retries at two. Clamp the effective retry count to DEFAULT_STRUCTURED_OUTPUT_MAX_RETRIES (while still handling negative values) before calculating max_attempts, so the public API cannot violate the stated safety limit.

        max_attempts = max(1, max_retries + 1)

src/devops_cli/ai/client/structured.py:140

• This new domain API raises a bare ValueError, contrary to the repository's exception convention: domain logic must raise a DevOpsCLIError-derived type (the existing LLMInferenceError hierarchy also preserves ValueError compatibility). Use the appropriate typed validation/domain exception here rather than exposing a built-in exception.

    raise ValueError("Either prompt or user text must be provided.")

• Files reviewed: 9/9 changed files
• Comments generated: 4
• Review effort level: Lite

---

💡 Add a code-review agent skill or configure MCP servers for context-aware, tailored reviews. Learn more in the docs.