Knowledge Assistant

A Flask-based web application that serves local procedures through an intelligent chat-like interface. The application provides a user-friendly way to search, access, and manage technical procedures and documentation.

Features

🤖 Intelligent Question Matching

• Intent Detection: Automatically detects user intent (commands-only, how-to, what-is, explain, general)
• Smart Scoring: Uses keyword matching and intent-based scoring to find the most relevant procedures
• Context-Aware Responses: Formats answers based on detected intent (e.g., shows only commands when requested)
• Retry Support: Allows users to retry previous questions easily

💬 Interactive Chat Interface

• Modern, responsive chat UI
• Conversation history with localStorage persistence
• Copy-to-clipboard functionality for commands
• Support for greetings and casual conversation (English and Bulgarian)
• Common question pattern recognition

👥 User Management

• Role-Based Access Control: Admin and regular user roles
• User Authentication: Secure password hashing with Werkzeug
• User Profile Management: Avatar selection, email updates, password changes
• Admin Features: Create, block/unblock, reset passwords, and delete users
• Default Superadmin: Auto-created on first run

📋 Procedure Management

• CRUD Operations: Create, read, update, and delete procedures
• Rich Content Support:
  • Step-by-step instructions
  • Commands with copy functionality
  • Images (summary, verification, notes)
  • File attachments (PDFs, documents, etc.)
  • Prerequisites and verification steps
  • Tags for better searchability
• Metadata Tracking: Created/updated by, timestamps
• Duplicate Prevention: Validates unique titles and IDs

📁 File Management

• File Uploads: Support for images and documents (max 16MB)
• Automatic Cleanup: Removes unused files when procedures are deleted or updated
• Secure Filenames: Uses secure_filename to prevent path traversal

🎨 Modern UI/UX

• Responsive design
• Dark theme with modern styling
• Font Awesome icons
• Smooth animations and transitions
• Mobile-friendly interface

Screenshots

Main Chat Interface

The main chat interface where users can interact with the Knowledge Assistant

User Management

User management interface showing profile management and user administration features

Procedure Administration

Procedure administration interface with live preview functionality

Requirements

• Python: 3.13 or higher
• Flask: >=3.0.0
• Werkzeug: >=3.0.0

Installation

1. Clone or Download the Project

cd /path/to/project

2. Create a Virtual Environment (Recommended)

python3 -m venv venv

3. Activate the Virtual Environment

On Linux/Mac:

source venv/bin/activate

On Windows:

venv\Scripts\activate

4. Install Dependencies

pip install -r requirements.txt

5. Set Environment Variables (Optional)

For production, set a secure secret key:

export SECRET_KEY='your-secure-secret-key-here'

6. Run the Application

python app.py

The application will be available at http://localhost:5000

Default Credentials

On first run, a default superadmin user is created:

• Username: superadmin
• Password: SuperAdmin@2024

⚠️ IMPORTANT: Change the default password immediately in production!

Project Structure

proj/
├── app.py                 # Main Flask application
├── greetings.py           # Greeting response handlers
├── common_responses.py    # Common question handlers
├── requirements.txt       # Python dependencies
├── INSTALLATION.md        # Detailed installation guide
├── static/                # Static files
│   ├── css/              # Stylesheets
│   │   ├── style.css
│   │   ├── admin.css
│   │   ├── auth.css
│   │   └── manage_users.css
│   ├── js/               # JavaScript files
│   │   ├── script.js
│   │   └── admin.js
│   ├── images/           # Images and avatars
│   │   └── avatars/
│   └── uploads/          # User-uploaded files
├── templates/            # HTML templates
│   ├── index.html        # Main chat interface
│   ├── admin.html        # Admin panel
│   ├── profile.html      # User profile page
│   └── login.html        # Login page
├── procedures/           # Procedure data storage
│   └── procedures.json
└── users/                # User data storage
    └── users.json

Usage

For Regular Users

1. Login: Use your credentials to access the application
2. Ask Questions: Type your question in the chat interface
3. Get Answers: The system will find and display relevant procedures
4. Copy Commands: Click the copy button next to any command
5. View Sources: Click on source links to see detailed procedure information
6. Manage Profile: Update your avatar, email, and password from the profile page

For Administrators

1. Admin Panel: Access /admin to manage procedures and users
2. Procedure Management:
   • Create new procedures with rich content
   • Edit existing procedures
   • Delete procedures (with automatic file cleanup)
   • Upload images and attachments
3. User Management:
   • Create new users
   • Block/unblock users
   • Reset user passwords
   • Delete users
4. View All Procedures: Browse and search all procedures in the system

Question Types Supported

The system intelligently handles different types of questions:

• Commands Only: "Give me the commands for X" → Shows only commands
• How-To: "How to install X" → Shows full step-by-step guide
• What-Is/Explain: "What is X" → Shows overview and explanation
• General: Other questions → Shows complete procedure information

API Endpoints

Authentication

• POST /login - User login
• /logout - User logout
• /profile - User profile page
• POST /profile/update - Update user profile

Procedures

• GET /procedures - List all procedures (requires login)
• POST /procedures - Create new procedure (requires login)
• PUT /procedures/<id> - Update procedure (requires login)
• DELETE /procedures/<id> - Delete procedure (requires login)

Chat

• POST /ask - Ask a question (requires login)

File Upload

• POST /upload - Upload files (requires login)

Admin

• /admin - Admin panel (requires admin role)
• POST /admin/users/create - Create user (admin only)
• POST /admin/users/<username>/block - Block/unblock user (admin only)
• POST /admin/users/<username>/reset-password - Reset password (admin only)
• DELETE /admin/users/<username>/delete - Delete user (admin only)

Configuration

File Upload Limits

• Maximum file size: 16MB (configurable in app.py)
• Allowed file types: Images, PDFs, documents

Data Storage

• Procedures: Stored in procedures/procedures.json
• Users: Stored in users/users.json
• Uploads: Stored in static/uploads/

Security

• Passwords are hashed using Werkzeug's password hashing
• Session-based authentication
• Secure filename handling for uploads
• CSRF protection (Flask default)

Troubleshooting

Issue: ModuleNotFoundError

Solution: Make sure you've activated the virtual environment and installed requirements:

source venv/bin/activate
pip install -r requirements.txt

Issue: Port Already in Use

Solution: Use a different port by modifying app.py:

app.run(host='0.0.0.0', port=5001, debug=True)

Issue: Permission Denied

Solution: Ensure the application has write permissions for:

• static/uploads/
• users/
• procedures/

Issue: No Procedures Found

Solution:

1. Check that procedures/procedures.json exists
2. Verify the JSON file is valid
3. Use the admin panel to create procedures

Issue: Login Not Working

Solution:

1. Check that users/users.json exists
2. Verify default superadmin credentials
3. Use reset_superadmin.py if needed to reset the superadmin password

Development

Running in Debug Mode

The application runs in debug mode by default. For production:

1. Set debug=False in app.py
2. Set a secure SECRET_KEY environment variable
3. Use a production WSGI server (e.g., Gunicorn, uWSGI)

Adding New Features

• New Response Types: Add patterns to greetings.py or common_responses.py
• UI Changes: Modify templates in templates/ and styles in static/css/
• Procedure Format: Extend the procedure JSON schema in app.py

License

This project is provided as-is for internal use and owned by 1NF1N172.

---

Note: This application stores data in JSON files. For production use with many users or large datasets, consider migrating to a proper database (PostgreSQL, MySQL, etc.).