CoolFace
Apppublic

takkars/aircraft-maintenance-rag

sourceHugging Faceupdated 1y agoView on Hugging Face
0likes
App README

Check out the configuration reference at https://huggingface.co/docs/hub/spaces-config-reference

Aircraft Maintenance RAG Assistant

A Retrieval-Augmented Generation (RAG) system designed to assist aircraft maintenance personnel by providing intelligent, context-aware recommendations based on historical maintenance records.

Features

  • —🔍 Semantic Search: Utilizes ChromaDB for efficient vector storage and similarity search
  • —🤖 LLM Integration: Flexible LLM access through OpenRouter.ai with local fallback options
  • —🔄 Advanced Retrieval: Supports MMR (Maximal Marginal Relevance) and multi-query retrieval
  • —📊 Metadata Filtering: Filter maintenance records by aircraft model, system, or other attributes
  • —💬 Interactive UI: User-friendly Gradio interface for natural language queries
  • —🏗️ Open Source: Built with LangChain for easy customization and extension

Installation

  1. 1.Clone the repository:
bash
git clone https://github.com/bhargavatakkars/aircraft-maintenance-rag.git
cd aircraft-maintenance-rag
  1. 1.Install dependencies:
bash
pip install -r requirements.txt
  1. 1.Set up OpenRouter API key:
  2. 2.Get your API key from OpenRouter.ai
  3. 3.For local development: Create a .env file with OPENROUTER_API_KEY=your_key_here
  4. 4.For Hugging Face Spaces: Add as a Space Secret in Settings → Variables
  1. 1.Run the application:
bash
./deploy.sh

Project Structure

  • —app.py: Gradio web interface implementation
  • —rag_pipeline.py: Core RAG system implementation using LangChain
  • —dummy_data.py: Synthetic maintenance records generator
  • —deploy.sh: Deployment script for local and Hugging Face Spaces
  • —requirements.txt: Python dependencies

Usage

  1. 1.Start the application:
bash
python app.py
  1. 1.Access the web interface at http://localhost:7860
  1. 1.Enter maintenance-related queries in natural language, such as:
  2. 2."What are common hydraulic pump failures on Boeing 737s?"
  3. 3."Show me recent landing gear issues in Airbus A320"
  4. 4."What maintenance actions were taken for electrical system faults?"

Advanced Features

MMR Search

Enable diverse document retrieval:

python
rag.configure_retriever(search_type="mmr", k=3, lambda_mult=0.5)

Multi-Query Retrieval

Enable query expansion for better results:

python
rag.enable_multi_query_retriever()

Metadata Filtering

Filter by specific aircraft or system:

python
rag.configure_retriever(filters={"aircraft_model": "Boeing 737", "system": "Hydraulic"})

Deployment on Hugging Face Spaces

Step 1: Get OpenRouter API Key

  1. 1.Go to OpenRouter.ai
  2. 2.Sign up/Login and navigate to API Keys
  3. 3.Create a new API key
  4. 4.Note down your API key (format: sk-or-v1-...)

Step 2: Create Hugging Face Space

  1. 1.Go to Hugging Face
  2. 2.Sign up/Login if you haven't already
  3. 3.Click on your profile picture → "New Space"
  4. 4.Fill in the Space creation form:
  5. 5.Owner: Select your account
  6. 6.Space name: aircraft-maintenance-rag
  7. 7.License: MIT
  8. 8.SDK: Gradio
  9. 9.Space hardware: CPU (Free tier)
  10. 10.Python version: 3.10

Step 3: Configure Space Settings

  1. 1.Go to your Space's Settings → Variables
  2. 2.Click "New Secret"
  3. 3.Add your OpenRouter API key:
  4. 4.Secret name: OPENROUTER_API_KEY
  5. 5.Secret value: Your API key from OpenRouter (sk-or-v1-...)
  6. 6.Click "Add Secret"

Step 4: Upload Project Files

Option 1: Using Git:

bash
git clone https://huggingface.co/spaces/YOUR_USERNAME/aircraft-maintenance-rag
cd aircraft-maintenance-rag
# Copy all project files here
git add .
git commit -m "Initial commit"
git push

Option 2: Using Web Interface:

  1. 1.Go to your Space's "Files" tab
  2. 2.Upload all project files:
  3. 3.app.py
  4. 4.rag_pipeline.py
  5. 5.dummy_data.py
  6. 6.deploy.sh
  7. 7.requirements.txt
  8. 8.README.md

Step 5: Verify Deployment

  1. 1.Wait for the automatic deployment to complete
  2. 2.Check the "App" tab to see your application running
  3. 3.Monitor the "Factory Logs" tab for any errors
  4. 4.Test the application by submitting a maintenance query

Troubleshooting

  • —If the app fails to load, check the "Factory Logs" for errors
  • —Verify that OPENROUTER_API_KEY is properly set in Space Secrets
  • —Ensure all dependencies in requirements.txt are correct
  • —Check that the model name in rag_pipeline.py matches: "mistralai/mistral-7b-instruct:free"

First-Time Deployment

On first deployment, the system will:

  1. 1.Create necessary directories (data/, chroma_db/)
  2. 2.Generate synthetic maintenance records
  3. 3.Build the vector store from scratch
  4. 4.This process may take a few minutes
  5. 5.Subsequent launches will reuse the existing data unless rebuild is forced

If you see "Building vector store..." message, this is normal for first deployment or when rebuilding is triggered.

OpenRouter Model Configuration

The system is configured to use mistralai/mistral-7b-instruct:free by default. To change models:

  1. 1.In rag_pipeline.py, locate the get_llm() method
  2. 2.Update the model name:
python
return ChatOpenRouter(
    model="mistralai/mistral-7b-instruct:free",  # or "deepseek-ai/deepseek-coder:free"
    openrouter_api_key=os.getenv("OPENROUTER_API_KEY")
)

Available free models and their specifications:

  • —mistralai/mistral-7b-instruct:free
  • —Context: 8K tokens
  • —Good for: General maintenance queries
  • —deepseek-ai/deepseek-coder:free
  • —Context: 16K tokens
  • —Good for: Technical procedures
  • —anthropic/claude-2:free
  • —Context: 100K tokens
  • —Good for: Complex analysis

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is open source and available under the MIT License.

Acknowledgments

  • —LangChain for the RAG framework
  • —ChromaDB for vector storage
  • —OpenRouter.ai for LLM access
  • —Gradio for the web interface