Skip to content

Installation Guide

Jump to bottom
LitapAI_Rohit edited this page Jul 8, 2026 · 1 revision

Installation Guide

This guide explains how to install and run MailIntel AI using either a local Python environment or Docker.

System Requirements

Recommended

  • Python 3.13 or later
  • Git
  • Docker Desktop (optional)
  • VS Code (recommended)

Supported operating systems:

  • macOS
  • Linux
  • Windows

Option 1: Local Installation (Recommended)

Clone the Repository

git clone https://github.com/Litap-AI/mailintel-ai.git

cd mailintel-ai

Create a Virtual Environment

macOS / Linux

python3 -m venv .venv

Activate:

source .venv/bin/activate

Windows

python -m venv .venv

.venv\Scripts\activate

Install Dependencies

pip install --upgrade pip

pip install -e ".[dev]"

Verify Installation

python --version

pip --version

python -m streamlit --version

Run MailIntel AI

python -m streamlit run src/mailintel/ui/app.py

Open your browser:

http://localhost:8501

Option 2: Docker Installation

Build

docker compose build

Start

docker compose up

Open:

http://localhost:8501

Stop

docker compose down

Running Tests

Execute the complete test suite:

pytest

Code Quality

Run Ruff:

ruff check .

ruff format . --check

Run MyPy:

mypy src

Run all pre-commit hooks:

pre-commit run --all-files

Project Structure

mailintel-ai/

src/
tests/
docs/
samples/

README.md
Dockerfile
docker-compose.yml
pyproject.toml

Sample Email

A sample email is available in:

samples/

Upload the sample through the dashboard to explore the application's features.

Updating the Project

Pull the latest changes:

git pull origin main

Update dependencies:

pip install -e ".[dev]"

Troubleshooting

ModuleNotFoundError

Ensure the virtual environment is activated.

Run the application using:

python -m streamlit run src/mailintel/ui/app.py

instead of:

streamlit run ...

This guarantees that the Streamlit installation from the active virtual environment is used.

Docker Build Fails

Verify Docker Desktop is running.

Rebuild the image:

docker compose build --no-cache

Tests Fail

Run:

pip install -e ".[dev]"

Then execute:

pytest

MyPy Errors

Ensure you're using the supported Python version and that development dependencies are installed.

Run:

mypy src

Getting Help

If you encounter an issue:

  1. Review the FAQ.
  2. Search existing GitHub Issues.
  3. Open a new Issue with:
    • Operating system
    • Python version
    • Error message
    • Steps to reproduce

Providing this information helps reproduce and resolve issues more efficiently.

Next Steps

After installation, explore:

  • Architecture
  • Investigation Workflow
  • Developer Guide
  • Threat Model
  • Roadmap

These documents provide a deeper understanding of the project's design and future direction.

Clone this wiki locally