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