Lazy Imports & Fast Startup

Optimize import time and memory usage with lazy loading

Lazy Imports & Fast Startup

PraisonAI Agents v0.5.0+ uses lazy imports to dramatically reduce startup time and memory usage. Heavy dependencies like litellm, requests, and chromadb are only loaded when actually needed.

from praisonaiagents import Agent

agent = Agent(name="MyAgent")  # litellm loads on first LLM call
agent.start("Hello")

The user imports PraisonAI and starts an agent instantly; heavy libraries load only on first use.

How It Works

Quick Start

1. Import without heavy deps

   from praisonaiagents import Agent
   
   agent = Agent(name="MyAgent")  # litellm loads on first LLM call
   
2. Verify lazy loading

   import sys
   import praisonaiagents
   
   assert "litellm" not in sys.modules
   print("Heavy dependencies not loaded at import time")
   

Performance Benefits

Metric	Before	After	Improvement
Import Time	820ms	18ms	97.8% faster
Memory Usage	93.3MB	33.0MB	64.6% reduction

How It Works

Lazy Module Loading

Core modules are loaded on-demand using Python’s __getattr__ mechanism:

# These imports are fast - modules loaded lazily
from praisonaiagents import Agent, Session, Memory, Knowledge

# Agent is only fully loaded when you use it
agent = Agent(name="MyAgent")  # litellm loaded here

Heavy Dependencies

The following dependencies are NOT loaded at import time:

• litellm - Only loaded when LLM calls are made
• requests - Only loaded when HTTP calls are needed
• chromadb - Only loaded when vector stores are used
• mem0 - Only loaded when memory features are used

Training & Vision Module Lazy Loading

Modules affected: praisonai.train.llm.trainer (the TrainModel class) and praisonai.upload_vision (the UploadVisionModel class) now use lazy loading to defer heavy ML dependencies.

These modules use a _lazy_import_*_deps() helper called from __init__, mirroring train.py / train_vision.py patterns.

Dependencies deferred:

• torch - CUDA/GPU computation framework
• transformers (TextStreamer, TrainingArguments) - Hugging Face transformers
• unsloth (FastLanguageModel, FastVisionModel, is_bfloat16_supported, standardize_sharegpt, get_chat_template) - Fast training optimization
• trl (SFTTrainer) - Transformer Reinforcement Learning
• datasets (load_dataset, concatenate_datasets) - Dataset loading utilities
• psutil (virtual_memory) - System memory monitoring

Impact: Importing praisonai.upload_vision or praisonai.train.llm.trainer is now near-instant; CUDA / ~2 GB of ML libs only load when you instantiate UploadVisionModel(...) or TrainModel(...).

# Fast — no torch/unsloth load
from praisonai.upload_vision import UploadVisionModel

# Heavy deps load here, not at import time
uploader = UploadVisionModel(config_path="config.yaml")

ImportError messages now include install hints:

• Vision upload: pip install torch unsloth
• Training: pip install torch transformers unsloth datasets trl psutil

Verifying Lazy Imports

You can verify lazy imports are working:

import sys

# Import the package
import praisonaiagents

# Check that heavy deps are NOT loaded
assert 'litellm' not in sys.modules
assert 'requests' not in sys.modules
assert 'chromadb' not in sys.modules

# Check training/vision modules are lazy loaded
from praisonai.upload_vision import UploadVisionModel  # noqa
assert "torch" not in sys.modules
assert "unsloth" not in sys.modules

print("✓ All heavy dependencies are lazy loaded")

Configuration

Lazy imports are enabled by default. You can check the configuration:

from praisonaiagents._config import LAZY_IMPORTS

print(f"Lazy imports enabled: {LAZY_IMPORTS}")

Best Practices

Import at point of use

Defer optional modules until a feature is invoked — keeps CLI and server startup fast.

Install extras only when needed

Use pip install praisonaiagents[memory] rather than pulling every optional dependency upfront.

Measure import time in CI

Track cold import duration to catch accidental module-level heavy imports in PRs.

Prefer lite for embedded use

Use the lite package when you bring your own LLM client and need minimal footprint.

# Good - specific imports
from praisonaiagents import Agent, Task

# Avoid - loads all modules
from praisonaiagents import *

Measuring Performance

Use the built-in benchmarks to measure import time:

import time

start = time.perf_counter()
import praisonaiagents
end = time.perf_counter()

print(f"Import time: {(end - start) * 1000:.1f}ms")

Related

Performance Benchmarks

Import time and memory metrics

Lite Package

Minimal BYO-LLM subpackage