dthart commited on
Commit
6d598a9
·
verified ·
1 Parent(s): fefd0a4

Upload 6 files

Browse files
Files changed (6) hide show
  1. README.md +226 -0
  2. app.py +144 -0
  3. inference_engine.py +177 -0
  4. knowledge_base.py +195 -0
  5. requirements.txt +3 -0
  6. test_cases.py +84 -0
README.md ADDED
@@ -0,0 +1,226 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ ---
2
+ title: Build 3 Starter - Explainable Decision Support
3
+ emoji: 🧠
4
+ colorFrom: yellow
5
+ colorTo: blue
6
+ sdk: gradio
7
+ sdk_version: 6.26.0
8
+ app_file: app.py
9
+ pinned: false
10
+ license: mit
11
+ ---
12
+
13
+ # Build 3 Starter: Explainable Decision Support Tool
14
+
15
+ This starter is a working knowledge-based application. The supplied example is
16
+ a Developer Connection Troubleshooter. It converts observations into explicit
17
+ facts, applies inspectable production rules, derives intermediate facts and
18
+ reports the rules that support each conclusion.
19
+
20
+ You should redesign the application for a new decision-support problem.
21
+ Submitting the starter unchanged does not demonstrate original work.
22
+
23
+ ## Architecture
24
+
25
+ ```text
26
+ Input
27
+ -> validation and normalization
28
+ -> structured facts
29
+ -> knowledge base
30
+ -> forward-chaining inference
31
+ -> supported conclusion or unknown
32
+ -> inference trace
33
+ -> human review
34
+ ```
35
+
36
+ No API key or pretrained model is required. A pretrained model may be added for
37
+ fact extraction or plain-language explanation, but it should not replace the
38
+ knowledge base or make the final decision independently.
39
+
40
+ ## Files
41
+
42
+ ```text
43
+ build_3_starter/
44
+ ├── app.py # Gradio interface
45
+ ├── knowledge_base.py # Explicit facts, rules, and recommendations
46
+ ├── inference_engine.py # Domain-independent forward chaining
47
+ ├── test_cases.py # Automated tests
48
+ ├── requirements.txt # Python dependency
49
+ └── README.md # Space configuration and instructions
50
+ ```
51
+
52
+ ## Run locally or in Colab (Recommended, but not Requird)
53
+
54
+ Use Python 3.10 or newer.
55
+
56
+ ```bash
57
+ python -m venv .venv
58
+ source .venv/bin/activate # Windows PowerShell: .venv\Scripts\Activate.ps1
59
+ python -m pip install --upgrade pip
60
+ python -m pip install -r requirements.txt
61
+ python -m unittest -v test_cases.py
62
+ python app.py
63
+ ```
64
+
65
+ Open the local URL printed by Gradio. Stop the server with `Ctrl+C`.
66
+
67
+ In Google Colab, upload all six files into the same directory, install the
68
+ requirements, and run the application:
69
+
70
+ ```python
71
+ !pip install -r requirements.txt
72
+ !python -m unittest -v test_cases.py
73
+ !python app.py
74
+ ```
75
+
76
+ For Colab preview only, change the final line of `app.py` temporarily to
77
+ `demo.launch(share=True)`. Do not commit `share=True` as a substitute for a
78
+ permanent deployment.
79
+
80
+ ## Deploy through the Hugging Face website
81
+
82
+ 1. Create or sign in to a Hugging Face account.
83
+ 2. Select **New Space** from the Spaces menu.
84
+ 3. Give the Space a name such as `build-3-decision-support`.
85
+ 4. Select **Gradio** as the SDK.
86
+ 5. Under **Hardware**, select **ZeroGPU (free)**. The starter contains a small
87
+ registered ZeroGPU startup probe so the free runtime can start. The actual
88
+ decision-support analysis remains CPU-only and does not enter the GPU queue.
89
+ 6. Choose Public visibility unless your instructor directs otherwise.
90
+ 7. Create the Space.
91
+ 8. Open the Space's **Files** tab.
92
+ 9. Upload all six files from this folder. The files must be at the repository
93
+ root, not inside another `build_3_starter` folder.
94
+ 10. Confirm that the repository root contains `app.py` and `README.md`.
95
+ 11. Wait for the Space status to change from Building to Running.
96
+ 12. Open the App tab and test all four supplied examples.
97
+ 13. Open the Space's public URL in a private/incognito window to verify that
98
+ another person can access it.
99
+
100
+ The YAML block at the top of this README tells Hugging Face to run `app.py` as a
101
+ Gradio Space.
102
+
103
+ ## Deploy with Git instead (Optional, although useful for your future projects)
104
+
105
+ After creating an empty Gradio Space, open its **Files** tab and copy the Git
106
+ repository URL. Then run:
107
+
108
+ ```bash
109
+ git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME
110
+ cd SPACE_NAME
111
+ ```
112
+
113
+ Copy the six starter files into that cloned directory, then:
114
+
115
+ ```bash
116
+ git add app.py knowledge_base.py inference_engine.py test_cases.py requirements.txt README.md
117
+ git commit -m "Create Build 3 decision-support application"
118
+ git push
119
+ ```
120
+
121
+ If Hugging Face requests authentication, use a Hugging Face user access token
122
+ with write permission instead of entering an account password in Git. Never put
123
+ the token in source code, `README.md`, screenshots or a public repository.
124
+
125
+ ## Successful-deployment checklist
126
+
127
+ - The Space status is **Running**.
128
+ - Space hardware is **ZeroGPU** when CPU Basic is unavailable on the account.
129
+ - The application loads without a Python traceback.
130
+ - The missing-authentication example reports Rule R6.
131
+ - The contradictory-input example displays a conflict warning.
132
+ - Unknown fields appear under **Information still unknown**.
133
+ - The represented-facts panel displays input and derived facts.
134
+ - `python -m unittest -v test_cases.py` passes all tests.
135
+ - No password, API key, token or private data is stored in the repository.
136
+ - The public application URL works in a signed-out browser window.
137
+
138
+ ## Troubleshooting deployment
139
+
140
+ ### Space reports `ModuleNotFoundError`
141
+
142
+ Confirm that `app.py`, `knowledge_base.py`, and `inference_engine.py` are in the
143
+ same repository directory and that the filenames match the imports exactly.
144
+
145
+ ### Space cannot find `app.py`
146
+
147
+ Confirm that the README metadata contains `app_file: app.py` and that `app.py`
148
+ is at the repository root.
149
+
150
+ ### Space remains in Building or shows Runtime error
151
+
152
+ Open the Space's **Logs** panel. Read the first Python exception rather than the
153
+ later cascade of errors. Correct the referenced filename and line, commit the
154
+ change and allow the Space to rebuild.
155
+
156
+ ### Runtime says `No @spaces.GPU function detected during startup`
157
+
158
+ The Space is using ZeroGPU but its current `app.py` does not contain the startup
159
+ probe supplied in this version of the starter. Confirm that `app.py` includes:
160
+
161
+ ```python
162
+ @spaces.GPU(duration=1)
163
+ def zerogpu_startup_probe():
164
+ return "ZeroGPU runtime registered"
165
+ ```
166
+
167
+ Upload the current `app.py`, commit the change, and restart the Space. The probe
168
+ is intentionally not connected to the Analyze button. The application's rule
169
+ engine does not need a GPU, and normal analyses should not consume GPU quota.
170
+
171
+ ### Interface runs but no conclusion is produced
172
+
173
+ This may be correct. The engine returns no supported conclusion when the facts
174
+ do not satisfy a rule. Inspect the inference trace and unknown-information list
175
+ before adding or changing a rule.
176
+
177
+ ## Student customization map
178
+
179
+ ### `knowledge_base.py`
180
+
181
+ Replace the supplied troubleshooting domain:
182
+
183
+ - Rename the input facts.
184
+ - Write at least two possible final conclusions.
185
+ - Add meaningful rules with domain-specific conditions.
186
+ - Include at least two rules with multiple conditions.
187
+ - Include at least one intermediate fact used by a later rule.
188
+ - Replace the recommendations.
189
+
190
+ ### `app.py`
191
+
192
+ - Rename the application and description.
193
+ - Replace the supplied questions with inputs appropriate to the new problem.
194
+ - Update the `analyze()` function's fact dictionary.
195
+ - Replace the examples with domain-specific tests.
196
+
197
+ ### `test_cases.py`
198
+
199
+ Replace or extend the tests so they verify:
200
+
201
+ 1. An expected supported conclusion.
202
+ 2. A different reasoning path.
203
+ 3. Missing information.
204
+ 4. Conflicting or boundary information.
205
+
206
+ ### `inference_engine.py`
207
+
208
+ The engine can usually remain unchanged. Students may extend it when their
209
+ domain needs comparisons, numeric ranges, negation or competing priorities.
210
+ Any extension should remain inspectable and covered by tests.
211
+
212
+ ## Optional pretrained-model extension
213
+
214
+ A model can propose structured facts from natural-language input:
215
+
216
+ ```text
217
+ Natural-language description
218
+ -> model proposes facts
219
+ -> user verifies or corrects facts
220
+ -> rule engine reasons over approved facts
221
+ -> application displays the supported conclusion
222
+ ```
223
+
224
+ The model must not invent missing facts or bypass the rule engine. Secrets used
225
+ by a Space belong in **Settings -> Variables and secrets**, never in code.
226
+
app.py ADDED
@@ -0,0 +1,144 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Gradio interface for Build 3: Explainable Decision Support Tool."""
2
+
3
+ import gradio as gr
4
+
5
+ try:
6
+ import spaces
7
+ except ImportError:
8
+ # Local/Colab fallback. Hugging Face ZeroGPU supplies the real package.
9
+ class _SpacesFallback:
10
+ @staticmethod
11
+ def GPU(*args, **kwargs):
12
+ def decorator(function):
13
+ return function
14
+
15
+ return decorator
16
+
17
+ spaces = _SpacesFallback()
18
+
19
+ from inference_engine import infer, render_report
20
+ from knowledge_base import NO, UNKNOWN, YES
21
+
22
+
23
+ CHOICES = [UNKNOWN, YES, NO]
24
+
25
+
26
+ @spaces.GPU(duration=1)
27
+ def zerogpu_startup_probe() -> str:
28
+ """Register one bounded GPU function so the free ZeroGPU runtime can start.
29
+
30
+ The application itself is a CPU-only rule engine and never calls this
31
+ function. Keeping the probe separate prevents ordinary analyses from
32
+ entering a GPU queue or consuming the user's ZeroGPU interaction quota.
33
+ """
34
+
35
+ return "ZeroGPU runtime registered"
36
+
37
+
38
+ def analyze(
39
+ backend_running: str,
40
+ health_check_passed: str,
41
+ request_reached_server: str,
42
+ cors_error_visible: str,
43
+ api_key_present: str,
44
+ status_code: str,
45
+ ) -> tuple[str, dict]:
46
+ facts = {
47
+ "backend_running": backend_running,
48
+ "health_check_passed": health_check_passed,
49
+ "request_reached_server": request_reached_server,
50
+ "cors_error_visible": cors_error_visible,
51
+ "api_key_present": api_key_present,
52
+ "status_code": status_code,
53
+ }
54
+ result = infer(facts)
55
+ visible_facts = {
56
+ **result.input_facts,
57
+ **{f"derived:{key}": value for key, value in result.derived_facts.items()},
58
+ }
59
+ return render_report(result), visible_facts
60
+
61
+
62
+ def clear_form():
63
+ return (UNKNOWN, UNKNOWN, UNKNOWN, UNKNOWN, UNKNOWN, "", "", {})
64
+
65
+
66
+ with gr.Blocks(title="Developer Connection Troubleshooter") as demo:
67
+ gr.Markdown(
68
+ """
69
+ # Developer Connection Troubleshooter
70
+
71
+ A small knowledge-based decision-support system. It represents observations
72
+ as facts, applies explicit rules, and shows an inference trace. Do not enter
73
+ an actual API key; report only whether a required credential is present.
74
+ """
75
+ )
76
+
77
+ with gr.Row():
78
+ with gr.Column():
79
+ backend_running = gr.Dropdown(
80
+ CHOICES, value=UNKNOWN, label="Is the backend running?"
81
+ )
82
+ health_check_passed = gr.Dropdown(
83
+ CHOICES, value=UNKNOWN, label="Does the health endpoint respond?"
84
+ )
85
+ request_reached_server = gr.Dropdown(
86
+ CHOICES, value=UNKNOWN, label="Did the request reach the server?"
87
+ )
88
+ with gr.Column():
89
+ cors_error_visible = gr.Dropdown(
90
+ CHOICES, value=UNKNOWN, label="Is a CORS error visible?"
91
+ )
92
+ api_key_present = gr.Dropdown(
93
+ CHOICES, value=UNKNOWN, label="Is the required credential present?"
94
+ )
95
+ status_code = gr.Textbox(
96
+ label="HTTP status code",
97
+ placeholder="For example: 200, 401, 404, or 500",
98
+ max_lines=1,
99
+ )
100
+
101
+ with gr.Row():
102
+ analyze_button = gr.Button("Analyze evidence", variant="primary")
103
+ clear_button = gr.Button("Clear")
104
+
105
+ with gr.Row():
106
+ report = gr.Markdown(label="Reasoning report")
107
+ represented_facts = gr.JSON(label="Represented facts")
108
+
109
+ gr.Examples(
110
+ examples=[
111
+ [YES, YES, YES, NO, NO, "401"],
112
+ [YES, YES, NO, YES, UNKNOWN, ""],
113
+ [NO, YES, UNKNOWN, UNKNOWN, UNKNOWN, ""],
114
+ [YES, YES, YES, NO, YES, "200"],
115
+ ],
116
+ inputs=[
117
+ backend_running,
118
+ health_check_passed,
119
+ request_reached_server,
120
+ cors_error_visible,
121
+ api_key_present,
122
+ status_code,
123
+ ],
124
+ label="Test cases",
125
+ )
126
+
127
+ inputs = [
128
+ backend_running,
129
+ health_check_passed,
130
+ request_reached_server,
131
+ cors_error_visible,
132
+ api_key_present,
133
+ status_code,
134
+ ]
135
+ analyze_button.click(analyze, inputs=inputs, outputs=[report, represented_facts])
136
+ clear_button.click(
137
+ clear_form,
138
+ outputs=[*inputs, report, represented_facts],
139
+ queue=False,
140
+ )
141
+
142
+
143
+ if __name__ == "__main__":
144
+ demo.launch()
inference_engine.py ADDED
@@ -0,0 +1,177 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Small, domain-independent forward-chaining inference engine."""
2
+
3
+ from dataclasses import dataclass, field
4
+ from typing import Any
5
+
6
+ from knowledge_base import INPUT_FACTS, RECOMMENDATIONS, RULES, UNKNOWN, Rule
7
+
8
+
9
+ @dataclass
10
+ class InferenceResult:
11
+ input_facts: dict[str, Any]
12
+ derived_facts: dict[str, Any]
13
+ diagnoses: list[str]
14
+ recommendations: list[str]
15
+ trace: list[str]
16
+ unknown_inputs: list[str]
17
+ conflicts: list[str] = field(default_factory=list)
18
+
19
+
20
+ def normalize_status_code(raw_value: Any) -> int | str:
21
+ """Return an integer status code or UNKNOWN for blank/invalid input."""
22
+
23
+ if raw_value in (None, "", UNKNOWN):
24
+ return UNKNOWN
25
+ try:
26
+ code = int(str(raw_value).strip())
27
+ except (TypeError, ValueError):
28
+ return UNKNOWN
29
+ return code if 100 <= code <= 599 else UNKNOWN
30
+
31
+
32
+ def status_class(code: int | str) -> str:
33
+ if not isinstance(code, int):
34
+ return UNKNOWN
35
+ return f"{code // 100}xx"
36
+
37
+
38
+ def _condition_matches(facts: dict[str, Any], name: str, expected: Any) -> bool:
39
+ """UNKNOWN never satisfies a condition unless a rule explicitly expects it."""
40
+
41
+ actual = facts.get(name, UNKNOWN)
42
+ return actual == expected
43
+
44
+
45
+ def _rule_matches(rule: Rule, facts: dict[str, Any]) -> bool:
46
+ return all(
47
+ _condition_matches(facts, name, expected)
48
+ for name, expected in rule.conditions.items()
49
+ )
50
+
51
+
52
+ def infer(input_facts: dict[str, Any]) -> InferenceResult:
53
+ """Apply rules repeatedly until no new fact or diagnosis can be produced."""
54
+
55
+ cleaned = dict(input_facts)
56
+ cleaned["status_code"] = normalize_status_code(cleaned.get("status_code"))
57
+ cleaned["status_class"] = status_class(cleaned["status_code"])
58
+
59
+ working_memory = dict(cleaned)
60
+ derived_facts: dict[str, Any] = {}
61
+ diagnoses: list[str] = []
62
+ trace: list[str] = []
63
+ conflicts: list[str] = []
64
+ fired_rules: set[str] = set()
65
+
66
+ ordered_rules = sorted(RULES, key=lambda rule: rule.priority, reverse=True)
67
+ changed = True
68
+ while changed:
69
+ changed = False
70
+ for rule in ordered_rules:
71
+ if rule.rule_id in fired_rules or not _rule_matches(rule, working_memory):
72
+ continue
73
+
74
+ fired_rules.add(rule.rule_id)
75
+ conditions = ", ".join(
76
+ f"{name}={expected}" for name, expected in rule.conditions.items()
77
+ )
78
+ trace.append(
79
+ f"{rule.rule_id} fired ({conditions}) -> "
80
+ f"{rule.conclusion_name}={rule.conclusion_value}. {rule.explanation}"
81
+ )
82
+
83
+ if rule.category == "diagnosis":
84
+ if rule.conclusion_value not in diagnoses:
85
+ diagnoses.append(str(rule.conclusion_value))
86
+ changed = True
87
+ elif rule.category == "conflict":
88
+ if rule.explanation not in conflicts:
89
+ conflicts.append(rule.explanation)
90
+ changed = True
91
+ else:
92
+ current = working_memory.get(rule.conclusion_name, UNKNOWN)
93
+ if current not in (UNKNOWN, rule.conclusion_value):
94
+ message = (
95
+ f"Conflicting values for {rule.conclusion_name}: "
96
+ f"{current!r} and {rule.conclusion_value!r}."
97
+ )
98
+ if message not in conflicts:
99
+ conflicts.append(message)
100
+ elif current != rule.conclusion_value:
101
+ working_memory[rule.conclusion_name] = rule.conclusion_value
102
+ derived_facts[rule.conclusion_name] = rule.conclusion_value
103
+ changed = True
104
+
105
+ recommendations: list[str] = []
106
+ for diagnosis in diagnoses:
107
+ for recommendation in RECOMMENDATIONS.get(diagnosis, []):
108
+ if recommendation not in recommendations:
109
+ recommendations.append(recommendation)
110
+
111
+ unknown_inputs = [
112
+ description
113
+ for name, description in INPUT_FACTS.items()
114
+ if cleaned.get(name, UNKNOWN) == UNKNOWN
115
+ ]
116
+
117
+ return InferenceResult(
118
+ input_facts=cleaned,
119
+ derived_facts=derived_facts,
120
+ diagnoses=diagnoses,
121
+ recommendations=recommendations,
122
+ trace=trace,
123
+ unknown_inputs=unknown_inputs,
124
+ conflicts=conflicts,
125
+ )
126
+
127
+
128
+ def render_report(result: InferenceResult) -> str:
129
+ """Render a human-readable, evidence-backed report for the interface."""
130
+
131
+ sections: list[str] = []
132
+
133
+ if result.conflicts:
134
+ lines = "\n".join(f"- {item}" for item in result.conflicts)
135
+ sections.append(
136
+ "## Conflicting information\n"
137
+ f"{lines}\n\nCorrect these inputs before accepting a recommendation."
138
+ )
139
+
140
+ if result.diagnoses:
141
+ lines = "\n".join(f"{index}. **{item}**" for index, item in enumerate(result.diagnoses, 1))
142
+ sections.append(f"## Supported conclusion(s)\n{lines}")
143
+ else:
144
+ sections.append(
145
+ "## No supported conclusion\n"
146
+ "The supplied facts did not activate a diagnostic rule. "
147
+ "Provide additional evidence or revise the knowledge base; do not guess."
148
+ )
149
+
150
+ if result.recommendations:
151
+ lines = "\n".join(f"- {item}" for item in result.recommendations)
152
+ sections.append(f"## Recommended checks\n{lines}")
153
+
154
+ if result.derived_facts:
155
+ lines = "\n".join(
156
+ f"- `{name}` = `{value}`" for name, value in result.derived_facts.items()
157
+ )
158
+ sections.append(f"## Derived facts\n{lines}")
159
+
160
+ if result.trace:
161
+ lines = "\n".join(f"- {item}" for item in result.trace)
162
+ sections.append(f"## Inference trace\n{lines}")
163
+
164
+ if result.unknown_inputs:
165
+ lines = "\n".join(f"- {item}" for item in result.unknown_inputs)
166
+ sections.append(
167
+ "## Information still unknown\n"
168
+ f"{lines}\n\nUnknown information was not treated as false."
169
+ )
170
+
171
+ sections.append(
172
+ "## Human review\n"
173
+ "Review the reported facts and inference trace before acting. "
174
+ "This starter demonstrates bounded reasoning and does not replace documentation, logs, or expert judgment."
175
+ )
176
+ return "\n\n".join(sections)
177
+
knowledge_base.py ADDED
@@ -0,0 +1,195 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Knowledge base for the supplied Developer Troubleshooting Assistant.
2
+
3
+ You should replace this domain with a new decision-support problem.
4
+ The Rule objects are intentionally explicit so the represented knowledge is
5
+ inspectable instead of hidden in a prompt or model weights.
6
+ """
7
+
8
+ from dataclasses import dataclass
9
+ from typing import Any
10
+
11
+
12
+ UNKNOWN = "Unknown"
13
+ YES = "Yes"
14
+ NO = "No"
15
+
16
+
17
+ @dataclass(frozen=True)
18
+ class Rule:
19
+ """A small production rule used by the forward-chaining engine."""
20
+
21
+ rule_id: str
22
+ description: str
23
+ conditions: dict[str, Any]
24
+ conclusion_name: str
25
+ conclusion_value: Any
26
+ explanation: str
27
+ category: str = "derived"
28
+ priority: int = 50
29
+
30
+
31
+ # Facts collected directly from the interface. This metadata is used to report
32
+ # missing information without treating UNKNOWN as False.
33
+ INPUT_FACTS = {
34
+ "backend_running": "whether the backend process is running",
35
+ "health_check_passed": "whether the backend health endpoint responds",
36
+ "request_reached_server": "whether the request reached the server",
37
+ "cors_error_visible": "whether the browser reports a CORS error",
38
+ "api_key_present": "whether the request includes the required credential",
39
+ "status_code": "the HTTP response status",
40
+ }
41
+
42
+
43
+ RULES = [
44
+ Rule(
45
+ "R1",
46
+ "Detect contradictory backend observations",
47
+ {"backend_running": NO, "health_check_passed": YES},
48
+ "input_conflict",
49
+ True,
50
+ "The backend was reported as stopped, but its health check was also reported as passing.",
51
+ category="conflict",
52
+ priority=100,
53
+ ),
54
+ Rule(
55
+ "R2",
56
+ "Derive that the network path is working",
57
+ {"health_check_passed": YES, "request_reached_server": YES},
58
+ "network_path_ok",
59
+ True,
60
+ "The health endpoint responded and the application request reached the server.",
61
+ category="derived",
62
+ priority=90,
63
+ ),
64
+ Rule(
65
+ "R3",
66
+ "Diagnose a stopped backend",
67
+ {"backend_running": NO},
68
+ "diagnosis",
69
+ "Backend is not running",
70
+ "A client cannot reach a backend process that has not started.",
71
+ category="diagnosis",
72
+ priority=90,
73
+ ),
74
+ Rule(
75
+ "R4",
76
+ "Diagnose a backend health or URL problem",
77
+ {"backend_running": YES, "health_check_passed": NO},
78
+ "diagnosis",
79
+ "Backend URL, port, or startup health problem",
80
+ "The process is reported as running, but its health endpoint does not respond.",
81
+ category="diagnosis",
82
+ priority=80,
83
+ ),
84
+ Rule(
85
+ "R5",
86
+ "Diagnose a likely CORS block",
87
+ {"request_reached_server": NO, "cors_error_visible": YES},
88
+ "diagnosis",
89
+ "Browser request blocked by CORS policy",
90
+ "The server did not receive the request and the browser displays a CORS error.",
91
+ category="diagnosis",
92
+ priority=85,
93
+ ),
94
+ Rule(
95
+ "R6",
96
+ "Diagnose missing authentication",
97
+ {"network_path_ok": True, "status_code": 401, "api_key_present": NO},
98
+ "diagnosis",
99
+ "Required authentication is missing",
100
+ "The server is reachable, returned HTTP 401, and no credential was included.",
101
+ category="diagnosis",
102
+ priority=95,
103
+ ),
104
+ Rule(
105
+ "R7",
106
+ "Diagnose rejected authentication",
107
+ {"network_path_ok": True, "status_code": 401, "api_key_present": YES},
108
+ "diagnosis",
109
+ "Credential is present but was rejected",
110
+ "The server is reachable and returned HTTP 401 even though a credential was included.",
111
+ category="diagnosis",
112
+ priority=90,
113
+ ),
114
+ Rule(
115
+ "R8",
116
+ "Diagnose authorization failure",
117
+ {"request_reached_server": YES, "status_code": 403},
118
+ "diagnosis",
119
+ "Authenticated user may lack permission",
120
+ "The server received the request but returned HTTP 403 Forbidden.",
121
+ category="diagnosis",
122
+ priority=85,
123
+ ),
124
+ Rule(
125
+ "R9",
126
+ "Diagnose a missing route or resource",
127
+ {"request_reached_server": YES, "status_code": 404},
128
+ "diagnosis",
129
+ "Endpoint or requested resource was not found",
130
+ "The server received the request and returned HTTP 404 Not Found.",
131
+ category="diagnosis",
132
+ priority=80,
133
+ ),
134
+ Rule(
135
+ "R10",
136
+ "Diagnose a server-side failure",
137
+ {"request_reached_server": YES, "status_class": "5xx"},
138
+ "diagnosis",
139
+ "Server-side application failure",
140
+ "The request reached the server and produced a 5xx response.",
141
+ category="diagnosis",
142
+ priority=80,
143
+ ),
144
+ Rule(
145
+ "R11",
146
+ "Recognize a successful request",
147
+ {"network_path_ok": True, "status_class": "2xx"},
148
+ "diagnosis",
149
+ "Connection appears successful",
150
+ "The health check passed, the request reached the server, and the response was successful.",
151
+ category="diagnosis",
152
+ priority=70,
153
+ ),
154
+ ]
155
+
156
+
157
+ RECOMMENDATIONS = {
158
+ "Backend is not running": [
159
+ "Start the backend and confirm that it remains running.",
160
+ "Open the health endpoint before testing the frontend again.",
161
+ ],
162
+ "Backend URL, port, or startup health problem": [
163
+ "Verify the backend URL and port used by the frontend.",
164
+ "Inspect backend startup logs and test the health endpoint directly.",
165
+ ],
166
+ "Browser request blocked by CORS policy": [
167
+ "Inspect the browser console and Network panel.",
168
+ "Allow the frontend origin in the backend CORS configuration.",
169
+ ],
170
+ "Required authentication is missing": [
171
+ "Confirm which authentication header the API requires.",
172
+ "Add the credential through a protected environment variable; do not hard-code it.",
173
+ ],
174
+ "Credential is present but was rejected": [
175
+ "Verify that the credential is current and sent in the expected header format.",
176
+ "Check its scope, audience and expiration without exposing the secret in logs.",
177
+ ],
178
+ "Authenticated user may lack permission": [
179
+ "Check the account role and the permission required by this endpoint.",
180
+ "Do not retry with broader privileges unless they are actually required.",
181
+ ],
182
+ "Endpoint or requested resource was not found": [
183
+ "Compare the requested path and HTTP method with the API documentation.",
184
+ "Check identifiers and route prefixes for spelling or environment differences.",
185
+ ],
186
+ "Server-side application failure": [
187
+ "Inspect the backend exception and request-correlated server logs.",
188
+ "Reproduce the failure with the smallest valid request before changing the frontend.",
189
+ ],
190
+ "Connection appears successful": [
191
+ "Inspect the returned data and the frontend code that renders it.",
192
+ "If the interface still fails, investigate client-side parsing or state management.",
193
+ ],
194
+ }
195
+
requirements.txt ADDED
@@ -0,0 +1,3 @@
 
 
 
 
1
+ gradio==6.26.0
2
+ spaces==0.51.1
3
+ socksio==1.0.0
test_cases.py ADDED
@@ -0,0 +1,84 @@
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
1
+ """Automated checks for the supplied inference engine.
2
+
3
+ Run locally with: python -m unittest -v test_cases.py
4
+ """
5
+
6
+ import unittest
7
+
8
+ from inference_engine import infer
9
+ from knowledge_base import NO, UNKNOWN, YES
10
+
11
+
12
+ class InferenceEngineTests(unittest.TestCase):
13
+ def test_missing_authentication_uses_derived_fact(self):
14
+ result = infer(
15
+ {
16
+ "backend_running": YES,
17
+ "health_check_passed": YES,
18
+ "request_reached_server": YES,
19
+ "cors_error_visible": NO,
20
+ "api_key_present": NO,
21
+ "status_code": "401",
22
+ }
23
+ )
24
+ self.assertTrue(result.derived_facts["network_path_ok"])
25
+ self.assertIn("Required authentication is missing", result.diagnoses)
26
+ self.assertTrue(any("R6 fired" in step for step in result.trace))
27
+
28
+ def test_cors_diagnosis(self):
29
+ result = infer(
30
+ {
31
+ "backend_running": YES,
32
+ "health_check_passed": UNKNOWN,
33
+ "request_reached_server": NO,
34
+ "cors_error_visible": YES,
35
+ "api_key_present": UNKNOWN,
36
+ "status_code": "",
37
+ }
38
+ )
39
+ self.assertIn("Browser request blocked by CORS policy", result.diagnoses)
40
+
41
+ def test_unknown_is_not_false(self):
42
+ result = infer(
43
+ {
44
+ "backend_running": UNKNOWN,
45
+ "health_check_passed": UNKNOWN,
46
+ "request_reached_server": UNKNOWN,
47
+ "cors_error_visible": UNKNOWN,
48
+ "api_key_present": UNKNOWN,
49
+ "status_code": "",
50
+ }
51
+ )
52
+ self.assertEqual(result.diagnoses, [])
53
+ self.assertGreaterEqual(len(result.unknown_inputs), 6)
54
+
55
+ def test_conflicting_observations_are_reported(self):
56
+ result = infer(
57
+ {
58
+ "backend_running": NO,
59
+ "health_check_passed": YES,
60
+ "request_reached_server": UNKNOWN,
61
+ "cors_error_visible": UNKNOWN,
62
+ "api_key_present": UNKNOWN,
63
+ "status_code": "",
64
+ }
65
+ )
66
+ self.assertTrue(result.conflicts)
67
+
68
+ def test_server_failure(self):
69
+ result = infer(
70
+ {
71
+ "backend_running": YES,
72
+ "health_check_passed": YES,
73
+ "request_reached_server": YES,
74
+ "cors_error_visible": NO,
75
+ "api_key_present": YES,
76
+ "status_code": "503",
77
+ }
78
+ )
79
+ self.assertIn("Server-side application failure", result.diagnoses)
80
+
81
+
82
+ if __name__ == "__main__":
83
+ unittest.main()
84
+