"""Knowledge base for the supplied Developer Troubleshooting Assistant. You should replace this domain with a new decision-support problem. The Rule objects are intentionally explicit so the represented knowledge is inspectable instead of hidden in a prompt or model weights. """ from dataclasses import dataclass from typing import Any UNKNOWN = "Unknown" YES = "Yes" NO = "No" @dataclass(frozen=True) class Rule: """A small production rule used by the forward-chaining engine.""" rule_id: str description: str conditions: dict[str, Any] conclusion_name: str conclusion_value: Any explanation: str category: str = "derived" priority: int = 50 # Facts collected directly from the interface. This metadata is used to report # missing information without treating UNKNOWN as False. INPUT_FACTS = { "backend_running": "whether the backend process is running", "health_check_passed": "whether the backend health endpoint responds", "request_reached_server": "whether the request reached the server", "cors_error_visible": "whether the browser reports a CORS error", "api_key_present": "whether the request includes the required credential", "status_code": "the HTTP response status", } RULES = [ Rule( "R1", "Detect contradictory backend observations", {"backend_running": NO, "health_check_passed": YES}, "input_conflict", True, "The backend was reported as stopped, but its health check was also reported as passing.", category="conflict", priority=100, ), Rule( "R2", "Derive that the network path is working", {"health_check_passed": YES, "request_reached_server": YES}, "network_path_ok", True, "The health endpoint responded and the application request reached the server.", category="derived", priority=90, ), Rule( "R3", "Diagnose a stopped backend", {"backend_running": NO}, "diagnosis", "Backend is not running", "A client cannot reach a backend process that has not started.", category="diagnosis", priority=90, ), Rule( "R4", "Diagnose a backend health or URL problem", {"backend_running": YES, "health_check_passed": NO}, "diagnosis", "Backend URL, port, or startup health problem", "The process is reported as running, but its health endpoint does not respond.", category="diagnosis", priority=80, ), Rule( "R5", "Diagnose a likely CORS block", {"request_reached_server": NO, "cors_error_visible": YES}, "diagnosis", "Browser request blocked by CORS policy", "The server did not receive the request and the browser displays a CORS error.", category="diagnosis", priority=85, ), Rule( "R6", "Diagnose missing authentication", {"network_path_ok": True, "status_code": 401, "api_key_present": NO}, "diagnosis", "Required authentication is missing", "The server is reachable, returned HTTP 401, and no credential was included.", category="diagnosis", priority=95, ), Rule( "R7", "Diagnose rejected authentication", {"network_path_ok": True, "status_code": 401, "api_key_present": YES}, "diagnosis", "Credential is present but was rejected", "The server is reachable and returned HTTP 401 even though a credential was included.", category="diagnosis", priority=90, ), Rule( "R8", "Diagnose authorization failure", {"request_reached_server": YES, "status_code": 403}, "diagnosis", "Authenticated user may lack permission", "The server received the request but returned HTTP 403 Forbidden.", category="diagnosis", priority=85, ), Rule( "R9", "Diagnose a missing route or resource", {"request_reached_server": YES, "status_code": 404}, "diagnosis", "Endpoint or requested resource was not found", "The server received the request and returned HTTP 404 Not Found.", category="diagnosis", priority=80, ), Rule( "R10", "Diagnose a server-side failure", {"request_reached_server": YES, "status_class": "5xx"}, "diagnosis", "Server-side application failure", "The request reached the server and produced a 5xx response.", category="diagnosis", priority=80, ), Rule( "R11", "Recognize a successful request", {"network_path_ok": True, "status_class": "2xx"}, "diagnosis", "Connection appears successful", "The health check passed, the request reached the server, and the response was successful.", category="diagnosis", priority=70, ), ] RECOMMENDATIONS = { "Backend is not running": [ "Start the backend and confirm that it remains running.", "Open the health endpoint before testing the frontend again.", ], "Backend URL, port, or startup health problem": [ "Verify the backend URL and port used by the frontend.", "Inspect backend startup logs and test the health endpoint directly.", ], "Browser request blocked by CORS policy": [ "Inspect the browser console and Network panel.", "Allow the frontend origin in the backend CORS configuration.", ], "Required authentication is missing": [ "Confirm which authentication header the API requires.", "Add the credential through a protected environment variable; do not hard-code it.", ], "Credential is present but was rejected": [ "Verify that the credential is current and sent in the expected header format.", "Check its scope, audience and expiration without exposing the secret in logs.", ], "Authenticated user may lack permission": [ "Check the account role and the permission required by this endpoint.", "Do not retry with broader privileges unless they are actually required.", ], "Endpoint or requested resource was not found": [ "Compare the requested path and HTTP method with the API documentation.", "Check identifiers and route prefixes for spelling or environment differences.", ], "Server-side application failure": [ "Inspect the backend exception and request-correlated server logs.", "Reproduce the failure with the smallest valid request before changing the frontend.", ], "Connection appears successful": [ "Inspect the returned data and the frontend code that renders it.", "If the interface still fails, investigate client-side parsing or state management.", ], }