Critical: Global installation fails - Need proper Python package structure

[FSSCoding]

🚨 Critical User Experience Issue

Problem Summary

The FSS-Mini-RAG installation creates a broken global experience for users. While the local ./rag-mini command works perfectly, the global installation either doesn't work or fails with confusing errors.

Current Broken Flow

1. Users run the installer expecting a global rag-mini command
2. The installer appears to succeed but doesn't create a working global command
3. Users try to run rag-mini from anywhere and it fails
4. This breaks the promised "easy setup and install" experience

Root Cause Analysis

The Fundamental Problem

FSS-Mini-RAG is implemented as a bash script with hardcoded relative paths, not a proper Python CLI package. This creates several critical issues:

# In rag-mini script - these paths only work from project directory
SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
local installed_python="$SCRIPT_DIR/.venv/bin/python3"

When installed globally, the script can't find:

• The .venv directory (expects it relative to script location)
• The requirements.txt files
• The Python modules in mini_rag/
• The bin/rag-mini.py entry point

Experimental Auto-Setup Mode Failure

The script falls back to "experimental auto-setup mode" which is designed to fail in most cases and shows scary warnings to users.

User Impact

• Broken first impressions: Users can't use the tool after "successful" installation
• Support burden: Multiple users reporting the same installation issues
• Reputation damage: "Easy setup" promise is false advertising
• Adoption barrier: Professional users expect proper CLI tool installation

Proper Solution: Modern Python Package Structure

The industry standard for Python CLI tools is proper package structure with entry points:

1. Convert to Proper Python Package

fss-mini-rag/
├── pyproject.toml          # Modern Python packaging
├── src/
│   └── fss_mini_rag/
│       ├── __init__.py
│       ├── cli.py          # Entry point
│       └── core/           # Core modules
└── README.md

2. Use pyproject.toml with Entry Points

[project.scripts]
rag-mini = "fss_mini_rag.cli:main"

3. Standard Installation Methods

Users should be able to install with:

pip install fss-mini-rag                    # From PyPI
pip install git+https://github.com/...     # From GitHub
pip install -e .                            # Development mode

4. Proper Virtual Environment Handling

• Use pip install which handles dependencies correctly
• No hardcoded paths to .venv directories
• Standard Python import system

Immediate Workaround for Users

Until fixed, document clearly:

# Don't use global installation - it's broken
# Instead, always run from project directory:
cd /path/to/fss-mini-rag
./rag-mini your-command-here

Implementation Priority

This is CRITICAL - it affects every new user's first experience. The current state makes the project appear amateurish despite excellent functionality.

References

• Python Packaging Guide
• Modern Python CLI with Click
• Entry Points Documentation

Success Criteria

• pip install fss-mini-rag works from any directory
• rag-mini command available globally after installation
• No bash scripts with hardcoded paths
• Standard Python packaging practices
• Users can install and use immediately without special setup