Wingfix is a retrieval-augmented generation (RAG) system designed for Aircraft Maintenance Engineers (AMEs) to quickly find accurate information from aviation technical documentation with proper effectivity filtering and citation tracking.
- 📚 Multi-Source Document Ingestion: Supports AMM, IPC, WDM, CMM, MEL, and internal policies (Comply365)
- 🔍 Hybrid Search: Combines text and vision-based retrieval for comprehensive results
✈️ Effectivity Filtering: Ensures answers are valid for specific tail numbers, dates, and fleet configurations- 📎 Citation Tracking: Every answer includes document revision, figure, and effectivity information
- 🔄 Precedence Resolution: Automatically prioritizes internal policies over OEM documentation
- 📦 Inventory Integration: Simulated TRAX integration for part availability checking
⚠️ CMM Handling: Clearly marks uncontrolled/legacy documents with acknowledgment requirements
┌─────────────────────────────────────────────────────────────────────────┐
│ Wingfix Architecture │
├─────────────────────────────────────────────────────────────────────────┤
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ FastAPI │ │ LangGraph │ │ Ollama │ │
│ │ REST API │──▶│ Agents │──▶│ LLM/VLM │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │ │ │
│ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Qdrant │ │ PostgreSQL │ │ MinIO │ │
│ │ Vectors │ │ Metadata │ │ Objects │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
└─────────────────────────────────────────────────────────────────────────┘
The fastest way to get started:
# 1. Drop your PDF manuals into data/incoming/
mkdir -p data/incoming
cp /path/to/your/manuals/*.pdf data/incoming/
# 2. Start everything with one command
./wingfix-start
# 3. Open http://localhost:5173 in your browser (React PWA)
# Stop with: ./wingfix-stop or Ctrl+CThat's it! The start script automatically handles:
- Virtual environment activation
- Docker infrastructure (PostgreSQL, Qdrant, MinIO, Redis)
- Database migrations
- Qdrant collection initialization
- Ollama LLM server
- WingFix API server
- React PWA frontend (Vite dev server on port 5173)
- Document ingestion from
data/incoming/
./wingfix-start # Start with React PWA (default)
./wingfix-start --cli # Start with interactive CLI
./wingfix-start --no-browser # Start React PWA but skip auto-opening browser
./wingfix-start --no-ingest # Skip document ingestion
./wingfix-start --no-cli # Start services only (no UI)
./wingfix-start --skip-migrations # Skip database migrations
./wingfix-start --help # Show all options- Python 3.11 or higher
- Node.js 18 or higher (for React PWA frontend)
- Docker and Docker Compose
- NVIDIA GPU with CUDA support (for model inference)
- 96GB GPU VRAM recommended (dual RTX A6000 or equivalent) for Gemma 4 31B Instruct (Q4_K_M quantized, 256k context)
If you prefer manual setup or need more control:
-
Clone the repository:
git clone https://github.com/wingfix/wingfix.git cd wingfix -
Create a virtual environment:
python -m venv .venv source .venv/bin/activate # On Windows: .venv\Scripts\activate
-
Install dependencies:
# For development (includes testing and code quality tools) pip install -e ".[dev]" # Or use requirements files for pinned versions pip install -r requirements-dev.txt
-
Set up environment variables:
cp .env.example .env # Edit .env with your configuration -
Start infrastructure services:
# Using the convenience script (recommended) ./scripts/start-infra.sh # Or using Docker Compose directly docker compose up -d # Verify services are healthy ./scripts/docker-health-check.sh
This starts:
- PostgreSQL 16: Metadata store (port 5432)
- Qdrant: Vector database (ports 6333/6334)
- MinIO: Object storage (ports 9000/9001)
- Redis: Caching layer (port 6379)
-
Run database migrations:
alembic upgrade head
-
Start the API server:
uvicorn wingfix.api.main:app --reload --port 8082
Set up pre-commit hooks for code quality:
pre-commit install
# Run on all files
pre-commit run --all-fileswingfix/
├── src/
│ ├── wingfix/
│ │ ├── __init__.py
│ │ ├── ingestion/ # Document ingestion pipeline
│ │ ├── enrichment/ # Entity extraction & enrichment
│ │ ├── storage/ # Database & storage layer
│ │ ├── indexing/ # Embedding & indexing
│ │ ├── retrieval/ # Search & retrieval
│ │ ├── agents/ # LangGraph agentic workflows
│ │ ├── api/ # FastAPI endpoints
│ │ └── utils/ # Utilities & helpers
│ └── tests/ # Test suite
├── configs/
│ ├── postgres/
│ │ └── init.sql # PostgreSQL initial schema
│ ├── qdrant/
│ │ └── config.yaml # Qdrant configuration
│ └── minio/
│ └── policy.json # MinIO bucket policies
├── scripts/
│ ├── wingfix-start.sh # One-command startup (all services)
│ ├── wingfix-stop.sh # One-command shutdown
│ ├── start-infra.sh # Start Docker services only
│ ├── stop-infra.sh # Stop Docker services only
│ ├── start_ollama.sh # Start Ollama server
│ ├── init_qdrant.py # Initialize Qdrant collections
│ └── docker-health-check.sh # Verify service health
├── data/ # Data directory (gitignored)
├── docs/ # Documentation
├── pyproject.toml # Project configuration
├── requirements.txt # Pinned dependencies
├── docker-compose.yml # Infrastructure services
├── docker-compose.override.yml.example # Dev overrides template
└── README.md
Wingfix uses a hierarchical configuration system:
- Environment Variables: Override all other settings
- Config Files:
configs/local.yamloverridesconfigs/default.yaml - Defaults: Built-in sensible defaults
Key configuration sections:
- Database: PostgreSQL, Qdrant, MinIO connections
- Models: Unified multimodal LLM (Gemma 4 31B Instruct) and embedding model paths
- Ingestion: Watch directories and supported formats
- Agent: Confidence thresholds, retry settings, and multi-step reasoning parameters
See .env.example for all available configuration options.
# Run all tests
pytest
# Run with coverage
pytest --cov=wingfix --cov-report=html
# Run specific test file
pytest src/tests/unit/test_pn_extractor.py
# Run only fast tests (skip slow/integration)
pytest -m "not slow and not integration"# Format code
black src/
ruff check --fix src/
# Type checking
mypy src/wingfix/
# All checks via pre-commit
pre-commit run --all-files# Create a new migration
alembic revision --autogenerate -m "Description"
# Apply migrations
alembic upgrade head
# Rollback one migration
alembic downgrade -1| Endpoint | Method | Description |
|---|---|---|
/api/v1/query |
POST | Main query endpoint for AME questions |
/api/v1/inventory/{pn} |
GET | Part number stock lookup |
/api/v1/documents |
GET | List documents with filters |
/api/v1/ingestion/jobs |
GET | Ingestion job status |
/health |
GET | Health check |
/docs |
GET | OpenAPI documentation |
- Agent Framework: LangGraph, LlamaIndex
- LLM Serving: Ollama
- Vector Database: Qdrant
- Relational Database: PostgreSQL with SQLAlchemy
- Object Storage: MinIO (S3-compatible)
- API Framework: FastAPI
- Embedding Models: bge-m3 (text), SigLIP (vision)
- Fork the repository
- Create a feature branch:
git checkout -b feature/my-feature - Make your changes with tests
- Run pre-commit hooks:
pre-commit run --all-files - Commit your changes:
git commit -m "Add my feature" - Push to the branch:
git push origin feature/my-feature - Open a Pull Request
This project is licensed under the MIT License - see the LICENSE file for details.
For questions or issues, please open a GitHub issue or contact the development team.
Built with ❤️ for Aircraft Maintenance Engineers