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.
|