feat: implement structured JSON schema for LLM response #26

[devangpratap]

Overview

Following the documentation and roadmap updates in #24, this PR provides the necessary technical refactor to align the LLM evaluation pipeline with modern production standards. It resolves the mismatch between the enforced response format and the internal parsing logic.

Resolved Issue

• Closes [Enhancement]: Align LLM response_format with expected JSON array structure in heuristic evaluation #26: Implements structured JSON schema validation for heuristic violations.

---

Technical Changes

1. Structured JSON Enforcement

• Strict Schema Implementation: Replaced the generic json_object format with a dedicated json_schema using strict: True in _evaluate_with_llm().
• Data Integrity: The schema explicitly defines a root "violations" key. Each item in the array is constrained to five required fields: criterion_id, severity (enum), description, recommendation, and affected_elements.
• Prompt Synchronization: Adjusted the system prompt to instruct the model to wrap findings in the new object structure, ensuring 100% compatibility with the schema.

2. Code Simplification & Cleanup

• Removal of Defensive Logic: Deleted the legacy block that manually iterated through potential keys like 'findings', 'results', or 'issues'.
• Direct Parsing: The engine now directly loads the verified "violations" key, reducing cyclomatic complexity and eliminating "key-guessing" failures.

---

Critical Dependency Check

• OpenAI SDK Requirements: This refactor utilizes json_schema strict mode, which requires OpenAI SDK v1.40.0+.
• Current Pin: The project currently pins openai>=1.3.7.
• Action Item: While fresh installs will pull the latest version, I recommend the maintainers consider bumping the minimum version in requirements.txt to 1.40.0 to prevent runtime errors in older environments.

Verification

• AST parse is clean for app/services/heuristic_engine.py.
• Python syntax verified; FastAPI service initializes correctly.