Build3pt2 / README.md
dthart's picture
Upload 6 files
6d598a9 verified
|
Raw History Blame Contribute Delete
7.76 kB

A newer version of the Gradio SDK is available: 6.32.0

Upgrade
metadata
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

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

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.

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:

!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:

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

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

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:

@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:

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.