Build3pt2 / README.md
dthart's picture
Upload 6 files
6d598a9 verified
|
Raw History Blame Contribute Delete
7.76 kB
---
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.