File size: 6,915 Bytes
6d598a9 | 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 108 109 110 111 112 113 114 115 116 117 118 119 120 121 122 123 124 125 126 127 128 129 130 131 132 133 134 135 136 137 138 139 140 141 142 143 144 145 146 147 148 149 150 151 152 153 154 155 156 157 158 159 160 161 162 163 164 165 166 167 168 169 170 171 172 173 174 175 176 177 178 179 180 181 182 183 184 185 186 187 188 189 190 191 192 193 194 195 196 | """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.",
],
}
|