Build3 / knowledge_base.py
dthart's picture
Upload 6 files
13bb5bb verified
Raw History Blame Contribute Delete
6.92 kB
"""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.",
],
}