|
Download README.md from dthart/Build3: direct link, hf CLI and curl.
- Browser
- Download file 7.76 kB
-
https://huggingface.co/spaces/dthart/Build3/resolve/main/README.md
- Command line
-
hf download hf://spaces/dthart/Build3/README.md
-
curl -L -o README.md https://huggingface.co/spaces/dthart/Build3/resolve/main/README.md
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. | |