File size: 7,760 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
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
---
title: Build 3 Starter - Explainable Decision Support
emoji: 🧠
colorFrom: yellow
colorTo: blue
sdk: gradio
sdk_version: 6.26.0
app_file: app.py
pinned: false
license: mit
---

# Build 3 Starter: Explainable Decision Support Tool

This starter is a working knowledge-based application. The supplied example is
a Developer Connection Troubleshooter. It converts observations into explicit
facts, applies inspectable production rules, derives intermediate facts and
reports the rules that support each conclusion.

You should redesign the application for a new decision-support problem.
Submitting the starter unchanged does not demonstrate original work.

## Architecture

```text
Input
-> validation and normalization
-> structured facts
-> knowledge base
-> forward-chaining inference
-> supported conclusion or unknown
-> inference trace
-> human review
```

No API key or pretrained model is required. A pretrained model may be added for
fact extraction or plain-language explanation, but it should not replace the
knowledge base or make the final decision independently.

## Files

```text
build_3_starter/
β”œβ”€β”€ app.py                 # Gradio interface
β”œβ”€β”€ knowledge_base.py      # Explicit facts, rules, and recommendations
β”œβ”€β”€ inference_engine.py    # Domain-independent forward chaining
β”œβ”€β”€ test_cases.py          # Automated tests
β”œβ”€β”€ requirements.txt       # Python dependency
└── README.md              # Space configuration and instructions
```

## Run locally or in Colab (Recommended, but not Requird)

Use Python 3.10 or newer.

```bash
python -m venv .venv
source .venv/bin/activate       # Windows PowerShell: .venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
python -m unittest -v test_cases.py
python app.py
```

Open the local URL printed by Gradio. Stop the server with `Ctrl+C`.

In Google Colab, upload all six files into the same directory, install the
requirements, and run the application:

```python
!pip install -r requirements.txt
!python -m unittest -v test_cases.py
!python app.py
```

For Colab preview only, change the final line of `app.py` temporarily to
`demo.launch(share=True)`. Do not commit `share=True` as a substitute for a
permanent deployment.

## Deploy through the Hugging Face website

1. Create or sign in to a Hugging Face account.
2. Select **New Space** from the Spaces menu.
3. Give the Space a name such as `build-3-decision-support`.
4. Select **Gradio** as the SDK.
5. Under **Hardware**, select **ZeroGPU (free)**. The starter contains a small
   registered ZeroGPU startup probe so the free runtime can start. The actual
   decision-support analysis remains CPU-only and does not enter the GPU queue.
6. Choose Public visibility unless your instructor directs otherwise.
7. Create the Space.
8. Open the Space's **Files** tab.
9. Upload all six files from this folder. The files must be at the repository
   root, not inside another `build_3_starter` folder.
10. Confirm that the repository root contains `app.py` and `README.md`.
11. Wait for the Space status to change from Building to Running.
12. Open the App tab and test all four supplied examples.
13. Open the Space's public URL in a private/incognito window to verify that
   another person can access it.

The YAML block at the top of this README tells Hugging Face to run `app.py` as a
Gradio Space.

## Deploy with Git instead (Optional, although useful for your future projects)

After creating an empty Gradio Space, open its **Files** tab and copy the Git
repository URL. Then run:

```bash
git clone https://huggingface.co/spaces/USERNAME/SPACE_NAME
cd SPACE_NAME
```

Copy the six starter files into that cloned directory, then:

```bash
git add app.py knowledge_base.py inference_engine.py test_cases.py requirements.txt README.md
git commit -m "Create Build 3 decision-support application"
git push
```

If Hugging Face requests authentication, use a Hugging Face user access token
with write permission instead of entering an account password in Git. Never put
the token in source code, `README.md`, screenshots or a public repository.

## Successful-deployment checklist

- The Space status is **Running**.
- Space hardware is **ZeroGPU** when CPU Basic is unavailable on the account.
- The application loads without a Python traceback.
- The missing-authentication example reports Rule R6.
- The contradictory-input example displays a conflict warning.
- Unknown fields appear under **Information still unknown**.
- The represented-facts panel displays input and derived facts.
- `python -m unittest -v test_cases.py` passes all tests.
- No password, API key, token or private data is stored in the repository.
- The public application URL works in a signed-out browser window.

## Troubleshooting deployment

### Space reports `ModuleNotFoundError`

Confirm that `app.py`, `knowledge_base.py`, and `inference_engine.py` are in the
same repository directory and that the filenames match the imports exactly.

### Space cannot find `app.py`

Confirm that the README metadata contains `app_file: app.py` and that `app.py`
is at the repository root.

### Space remains in Building or shows Runtime error

Open the Space's **Logs** panel. Read the first Python exception rather than the
later cascade of errors. Correct the referenced filename and line, commit the
change and allow the Space to rebuild.

### Runtime says `No @spaces.GPU function detected during startup`

The Space is using ZeroGPU but its current `app.py` does not contain the startup
probe supplied in this version of the starter. Confirm that `app.py` includes:

```python
@spaces.GPU(duration=1)
def zerogpu_startup_probe():
    return "ZeroGPU runtime registered"
```

Upload the current `app.py`, commit the change, and restart the Space. The probe
is intentionally not connected to the Analyze button. The application's rule
engine does not need a GPU, and normal analyses should not consume GPU quota.

### Interface runs but no conclusion is produced

This may be correct. The engine returns no supported conclusion when the facts
do not satisfy a rule. Inspect the inference trace and unknown-information list
before adding or changing a rule.

## Student customization map

### `knowledge_base.py`

Replace the supplied troubleshooting domain:

- Rename the input facts.
- Write at least two possible final conclusions.
- Add meaningful rules with domain-specific conditions.
- Include at least two rules with multiple conditions.
- Include at least one intermediate fact used by a later rule.
- Replace the recommendations.

### `app.py`

- Rename the application and description.
- Replace the supplied questions with inputs appropriate to the new problem.
- Update the `analyze()` function's fact dictionary.
- Replace the examples with domain-specific tests.

### `test_cases.py`

Replace or extend the tests so they verify:

1. An expected supported conclusion.
2. A different reasoning path.
3. Missing information.
4. Conflicting or boundary information.

### `inference_engine.py`

The engine can usually remain unchanged. Students may extend it when their
domain needs comparisons, numeric ranges, negation or competing priorities.
Any extension should remain inspectable and covered by tests.

## Optional pretrained-model extension

A model can propose structured facts from natural-language input:

```text
Natural-language description
-> model proposes facts
-> user verifies or corrects facts
-> rule engine reasons over approved facts
-> application displays the supported conclusion
```

The model must not invent missing facts or bypass the rule engine. Secrets used
by a Space belong in **Settings -> Variables and secrets**, never in code.