GlossView

GlossView is a Python CLI project that turns words and local images into structured explanations. It started as an academic intelligent-systems requirement and has been modernized into a small, reviewable portfolio project.

The app supports two lookup modes:

• Word lookup: define English words and short terms with part of speech, examples, and synonyms.
• Image understanding: classify local images, describe the likely subject, and explain its everyday meaning.

GlossView runs offline by default with NLTK WordNet and torchvision ResNet-50. If Azure OpenAI settings are configured, it can try online AI responses first and fall back to the offline path when the API is unavailable.

Why This Project Is Portfolio-Ready

• Demonstrates practical Python module organization without over-engineering.
• Combines classic NLP data, computer vision inference, optional online AI, and CLI interaction in one focused project.
• Keeps the original academic purpose visible while improving maintainability, tests, error handling, and documentation.
• Uses structured result helpers so the same logic can support the CLI today and a Streamlit or web UI later.

Features

• Define English words and short terms.
• Return part of speech, pronunciation field, definition, examples, and synonyms.
• Describe local image files with a label, description, meaning, and confidence score when available.
• Validate missing files, unsupported formats, empty input, and low-confidence image predictions.
• Use offline models by default, with optional Azure OpenAI fallback.
• Apply a lightweight safety filter for clearly unsafe requests.
• Provide structured Python APIs: define_word_json and describe_image_json.
• Include standard-library tests that avoid network calls and heavy model loading.

Tech Stack

• Python 3.10+
• NLTK WordNet for lexical lookup
• PyTorch and torchvision for ResNet-50 image classification
• Pillow for image loading
• requests for optional Azure OpenAI calls
• unittest for automated validation

Project Structure

.
|-- src/
|   |-- __init__.py
|   |-- ai_clients.py          # Optional Azure OpenAI integration
|   |-- image_bot.py           # Image validation, classification, formatting
|   |-- main.py                # CLI entry point
|   |-- safety.py              # Lightweight keyword safety filter
|   |-- word_bot.py            # WordNet lookup and formatting
|   `-- prompts/
|       |-- image_prompts.txt
|       `-- word_prompts.txt
|-- tests/
|   |-- test_ai_clients.py
|   |-- test_images.py
|   |-- test_safety.py
|   `-- test_words.py
|-- docs/
|   |-- PROJECT_NOTES.md
|   `-- screenshots/
|       |-- error-state.png
|       |-- image-description.png
|       `-- word-lookup.png
|-- prompt_justification.md
|-- requirements.txt
`-- README.md

Setup

Create and activate a virtual environment:

python -m venv .venv

Windows PowerShell:

.\.venv\Scripts\Activate.ps1

macOS or Linux:

source .venv/bin/activate

Install dependencies:

pip install -r requirements.txt

Install the WordNet data used by the offline dictionary:

python -m nltk.downloader wordnet omw-1.4

The first image classification may download torchvision's ResNet-50 weights if they are not already cached locally.

Usage

Start the CLI:

python -m src.main

Available commands:

define <word>       Look up a word or short English term.
describe <image>    Describe an image file by path.
help                Show command help.
exit, quit          Close GlossView.

Word Lookup Example

> define serendipity
[word]
  serendipity
[part_of_speech]
  noun
[pronunciation]
  N/A
[definition]
  good luck in making unexpected and fortunate discoveries
[examples]
  - Finding that rare book was a moment of serendipity.
[synonyms]
  chance, fortune, luck

Image Description Example

> describe path/to/image.jpg
[label]
  tabby
[description]
  A tabby cat with distinctive striped or spotted fur markings.
[meaning]
  A domestic cat pattern; one of the most common coat types in household cats.
[confidence]
  87.34%

Error Handling Example

> describe ./missing-file.jpg
[label]
  unknown
[description]
  File not found: ./missing-file.jpg
[meaning]
  N/A

Optional Online AI Mode

The offline path is the default. To try Azure OpenAI responses first and fall back to offline logic on failure, set these environment variables.

Windows PowerShell:

$env:USE_ONLINE_AI = "true"
$env:AZURE_OPENAI_API_KEY = "your-key"
$env:AZURE_OPENAI_ENDPOINT = "https://your-resource.openai.azure.com"
$env:AZURE_OPENAI_MODEL = "your-deployment-name"

macOS or Linux:

export USE_ONLINE_AI=true
export AZURE_OPENAI_API_KEY=your-key
export AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com
export AZURE_OPENAI_MODEL=your-deployment-name

Prompts live in src/prompts/, and the prompt design rationale is documented in prompt_justification.md.

Running Tests

Run the standard-library test suite:

python -m unittest discover -s tests -v

Run a syntax check:

python -m py_compile src/main.py src/word_bot.py src/image_bot.py src/ai_clients.py src/safety.py

Screenshots

Captured CLI screenshots are stored under docs/screenshots/.

• Word lookup screenshot: docs/screenshots/word-lookup.png
• Image description screenshot: docs/screenshots/image-description.png
• Error handling screenshot: docs/screenshots/error-state.png

Documentation

• docs/PROJECT_NOTES.md: reviewer-focused summary of the academic origin, modernization decisions, limitations, and possible next steps.
• prompt_justification.md: prompt design rationale for the optional online AI path.

Current Limitations

• Image classification is limited to ImageNet's 1,000 classes, so unusual subjects may be labeled broadly or returned as unknown.
• WordNet does not provide pronunciation data, so offline pronunciation remains N/A.
• The safety filter is intentionally lightweight and keyword-based.
• GlossView is currently CLI-first. A small Streamlit or web UI would be a natural future upgrade, but it is intentionally not included yet.