Installation

Maticlib can be installed in multiple ways depending on your needs. Choose the installation method that best suits your project requirements.

System Requirements

Before installing Maticlib, ensure your system meets these requirements:

Dependencies

Maticlib requires the following Python packages (automatically installed):

Install from PyPI (Recommended)

The easiest and recommended way to install Maticlib is from PyPI using pip:

pip install maticlib

This command will install the latest stable version along with all required dependencies.

Upgrade to Latest Version

To upgrade an existing installation to the latest version:

pip install --upgrade maticlib

Install from TestPyPI

To test pre-release versions or development builds from TestPyPI:

pip install -i https://test.pypi.org/simple/ --extra-index-url https://pypi.org/simple/ maticlib
⚠️ Warning: TestPyPI packages may be unstable and are intended for testing purposes only. Use at your own risk.

Install from Source

To install the latest development version directly from GitHub:

git clone https://github.com/arvohsoft/maticlib.git
cd maticlib
pip install -e .

The -e flag installs the package in editable mode, which is useful if you want to modify the source code.

Development Installation

If you want to contribute to Maticlib or need development tools, install it with dev dependencies:

# Clone the repository
git clone https://github.com/arvohsoft/maticlib.git
cd maticlib

# Create a virtual environment (recommended)
python -m venv venv

# Activate virtual environment
# On Linux/Mac:
source venv/bin/activate

# On Windows:
venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Development dependencies include:

Virtual Environment Setup

It's strongly recommended to use a virtual environment to isolate your project dependencies:

Using venv (Built-in)

# Create virtual environment
python -m venv maticlib-env

# Activate on Linux/Mac
source maticlib-env/bin/activate

# Activate on Windows
maticlib-env\Scripts\activate

# Install maticlib
pip install maticlib

Using conda

# Create conda environment
conda create -n maticlib python=3.10

# Activate environment
conda activate maticlib

# Install maticlib
pip install maticlib

Verify Installation

After installation, verify that Maticlib is installed correctly:

python -c "import maticlib; print(maticlib.__version__)"

You should see the version number printed. If you see an error, the installation may have failed.

Check Installed Components

python -c "from maticlib.llm.google_genai import GoogleGenAIClient; print('✓ Google GenAI Client available')"
python -c "from maticlib.llm.mistral import MistralClient; print('✓ Mistral Client available')"
python -c "from maticlib.graph import MaticGraph; print('✓ MaticGraph available')"

API Key Setup

Set up your API keys as environment variables for secure access:

Linux/Mac

# Temporary (current session only)
export GOOGLE_API_KEY="your-google-api-key"
export MISTRAL_API_KEY="your-mistral-api-key"

# Permanent (add to ~/.bashrc or ~/.zshrc)
echo 'export GOOGLE_API_KEY="your-google-api-key"' >> ~/.bashrc
echo 'export MISTRAL_API_KEY="your-mistral-api-key"' >> ~/.bashrc
source ~/.bashrc

Windows (PowerShell)

# Temporary (current session only)
$env:GOOGLE_API_KEY="your-google-api-key"
$env:MISTRAL_API_KEY="your-mistral-api-key"

# Permanent (system-wide)
[Environment]::SetEnvironmentVariable("GOOGLE_API_KEY", "your-google-api-key", "User")
[Environment]::SetEnvironmentVariable("MISTRAL_API_KEY", "your-mistral-api-key", "User")

Windows (Command Prompt)

# Temporary (current session only)
set GOOGLE_API_KEY=your-google-api-key
set MISTRAL_API_KEY=your-mistral-api-key

# Permanent (use setx)
setx GOOGLE_API_KEY "your-google-api-key"
setx MISTRAL_API_KEY "your-mistral-api-key"

Using .env File (Recommended)

Create a .env file in your project root:

GOOGLE_API_KEY=your-google-api-key
MISTRAL_API_KEY=your-mistral-api-key

Then load it using python-dotenv:

pip install python-dotenv

# In your Python script
from dotenv import load_dotenv
load_dotenv()

from maticlib.llm.google_genai import GoogleGenAIClient
client = GoogleGenAIClient()  # API key loaded from .env
💡 Tip: Always add .env to your .gitignore file to prevent accidentally committing sensitive API keys to version control.

Obtaining API Keys

Google Gemini API Key

  1. Visit Google AI Studio
  2. Sign in with your Google account
  3. Click "Get API Key" in the dashboard
  4. Copy the generated API key

Mistral AI API Key

  1. Visit Mistral AI Console
  2. Create an account or sign in
  3. Navigate to API Keys section
  4. Generate a new API key
  5. Copy the key (it won't be shown again)

Troubleshooting

Installation Fails

If installation fails, try:

# Update pip
pip install --upgrade pip

# Install with --user flag
pip install --user maticlib

# Use Python 3 explicitly
python3 -m pip install maticlib

Import Errors

If you get import errors after installation:

Version Conflicts

If you encounter dependency conflicts:

# Create a fresh virtual environment
python -m venv fresh-env
source fresh-env/bin/activate  # or fresh-env\Scripts\activate on Windows
pip install maticlib

Uninstalling

To completely remove Maticlib:

pip uninstall maticlib

Docker Installation (Optional)

For containerized deployments, create a Dockerfile:

FROM python:3.10-slim

WORKDIR /app

# Install maticlib
RUN pip install maticlib

# Copy your application
COPY . .

CMD ["python", "your_app.py"]

Build and run:

docker build -t my-maticlib-app .
docker run -e GOOGLE_API_KEY=your-key my-maticlib-app

Next Steps

Now that you have Maticlib installed:

Need Help?

If you encounter issues during installation: