AIMLite

The Django for AI & Machine Learning — an opinionated, convention-over-configuration Python framework with zero-path CLI execution.

PyPI Installation

pip install aimlite

Or with uv:

uv add aimlite

from aimlite import Model, Dataset, BaseTrainer, BaseConfig, BaseEvaluator, BaseInference

Authors & Collaborators

• Mickyas Tesfaye (alazartesfaye42@gmail.com)
• Beamlak Tadesse (atocodes@gmail.com)

Why AIMLite?

Traditional AI and machine learning projects suffer from repetitive boilerplate: scattered scripts, brittle path configurations, unstandardized train/test splits, hardcoded checkpoint paths, and ad-hoc serving code.

AIMLite provides a standardized, convention-based structure inspired by modern web frameworks like Django and Vite:

• Zero-Path Execution: Run aimlite anywhere inside your project directory. AIMLite resolves modules, sets up paths, and locates your data and models automatically.
• Automated Virtual Environment Management: Automatically creates .venv and pre-installs aimlite on init.
• Instant IDE Type Safety: Because aimlite is installed in the project .venv with PEP 561 headers (py.typed), editors like VS Code, Cursor, and PyCharm deliver immediate auto-completion, parameter hints, and docstrings with zero configuration.
• Per-Model Artifacts & Lifecycle: Supports multiple model classes per project with standardized naming (models/<model_name>.pkl and experiments/<model_name>_snapshot.json).
• Built-in Inference Serving: Production-ready HTTP server with POST /predict, GET /health, GET /docs, custom user-defined endpoints, and optional static frontend hosting.

Quickstart

Requires Python >= 3.10 (tested on 3.14) and uv (or pip).

git clone https://github.com/Alazar42/aimlite.git
cd aimlite
uv sync

Essential Commands

uv run aimlite --help         # Run AIMLite CLI
uv run test                   # Run core test suite (42 tests)
uv run pytest                 # Full pytest runner

Project Structure Conventions

When you run aimlite init <project_name> (or aimlite init .), AIMLite scaffolds a clean, convention-based layout:

my_project/
├── .venv/                    # Project-isolated virtual environment with aimlite pre-installed
├── data/                     # Raw datasets (.csv, .json, .parquet, .txt, etc.)
├── models/                   # Serialized production models and saved weights (*.pkl)
├── experiments/              # Training run logs and metric snapshots (*.json)
├── artifacts/                # Generated artifacts, vector embeddings, and outputs
├── checkpoints/              # Model weights and checkpoint deltas
├── my_project/               # Python application package
│   ├── __init__.py
│   ├── config.py             # Project configuration
│   ├── data.py               # Dataset definitions extending Dataset
│   ├── model.py              # Model classes extending Model
│   ├── trainer.py            # Training lifecycle hooks extending BaseTrainer
│   ├── evaluator.py          # Metric benchmarks extending BaseEvaluator
│   └── inference.py          # Inference pipeline extending BaseInference
└── aimlite.json              # Project manifest and config

Flexible Dataset Naming (Any File, Any Format)

AIMLite gives developers total freedom over data file names and formats. You are never forced to use specific filenames or conventions.

Simply declare filename = "<your_filename>" on your Dataset subclass to match any file placed inside data/:

from aimlite import Dataset

class UserChurnDataset(Dataset):
    filename = "telecom_churn.csv"  # Name it whatever you want!

class MonthlySalesDataset(Dataset):
    filename = "sales_q4_2026.parquet"

class LogAuditDataset(Dataset):
    filename = "system_logs.jsonl"

You can also pass source directly when instantiating or calling load():

dataset = UserChurnDataset(source="data/custom_export.csv")

Supported Data Formats Out-of-the-Box

• Tabular: CSV (.csv), TSV (.tsv, .tab)
• JSON: Structured JSON arrays (.json), newline-delimited JSON (.jsonl)
• Columnar: Apache Parquet (.parquet, .pq)
• Text & Docs: Plain text (.txt), Markdown (.md)

Unconstrained Modeling & Reference Templates

AIMLite is completely unopinionated about your modeling choices and does not force you into fixed paradigms. You can build any AI or machine learning system you want:

• Classical & Tabular ML (scikit-learn, XGBoost, LightGBM, CatBoost)
• Deep Neural Networks (PyTorch, TensorFlow, JAX)
• LLMs & Prompt Pipelines (LangChain, LlamaIndex, vLLM, Ollama, Hugging Face)
• Computer Vision & Multimodal (torchvision, timm, albumentations)
• Reinforcement Learning & Custom Heuristics

You can use any file name and any data format across all workflows. Simply declare filename = "<your_filename>" on your Dataset class or pass source directly.

The following reference implementations in docs/examples/ are simply starting templates to demonstrate project structure — you are free to adapt, replace, or build completely custom workflows:

Reference Template 1: Tabular ML (e.g. Churn Classifier)

Demonstrates a standard supervised learning workflow with feature preprocessing, scikit-learn models, and metric evaluation. You can use any tabular format (CSV, Parquet, TSV, etc.) with any filename you choose.

• Example Implementation: docs/examples/churn_scratch/
  • data.py: TelecomChurnDataset(Dataset) declaring filename = "telecom_churn.csv" with automatic 80/10/10 train/val/test splits.
  • model.py: ChurnClassifier(Model) wrapping scikit-learn's RandomForestClassifier.
  • trainer.py: ChurnTrainer(BaseTrainer) fitting and saving weights to models/churn_classifier.pkl.
  • evaluator.py: ChurnEvaluator(BaseEvaluator) calculating accuracy, precision, recall, and F1 score.
  • inference.py: ChurnInference(BaseInference) scoring churn risk probability and returning retention decisions.
• Workflow:

  # Initialize (new directory or in-place with .)
  aimlite init churn_model && cd churn_model
  # Place your data file in data/
  aimlite data validate
  aimlite train ChurnClassifier
  aimlite evaluate ChurnClassifier
  aimlite serve ChurnClassifier --port 8000
  

Reference Template 2: Knowledge Base & RAG

Demonstrates semantic vector retrieval and context augmentation. Ingest text, Markdown, CSV, JSON, or any document source with any filename you choose.

• Example Implementation: docs/examples/knowledge_rag/
  • data.py: KnowledgeDocsDataset(Dataset) chunking text passages.
  • model.py: SupportDocRAG(RAGModel) binding MemoryVectorStore and VectorRetriever.
  • trainer.py: IndexBuilderTrainer(BaseTrainer) building and persisting the vector index to models/rag_index.json.
  • inference.py: RAGInference(BaseInference) querying the retriever and synthesizing grounded answers with citations.
• Workflow:

  aimlite init support_rag && cd support_rag
  # Place your knowledge documents in data/
  aimlite train SupportDocRAG
  aimlite serve SupportDocRAG --port 8000
  

Reference Template 3: Fine-Tuning & Adapters (LoRA & PEFT)

Demonstrates parameter-efficient fine-tuning with lightweight delta checkpoints. Ingest any prompt format, CSV, Parquet, JSON, JSONL, or custom schema with any filename you choose.

• Example Implementation: docs/examples/instruction_adapter/
  • data.py: InstructionDataset(Dataset) preparing fine-tuning data.
  • model.py: LoRAInstructionModel(AdapterModel) configuring adapter rank and alpha.
  • trainer.py: AdapterInstructionTrainer(BaseTrainer) optimizing low-rank delta matrices.
  • inference.py: AdapterInference(BaseInference) executing fine-tuned generations via POST /predict.
• Workflow:

  aimlite init lora_app && cd lora_app
  # Place your dataset file in data/
  aimlite train LoRAInstructionModel
  aimlite serve LoRAInstructionModel --port 8000
  

Zero-Path CLI Reference

AIMLite provides zero-path convention-over-configuration commands:

Standalone Executable & Build System (build/)

The standalone binary is packaged using Python's native zipapp format into a single self-contained executable with zero runtime dependencies:

# Compile / rebuild the standalone binary:
python3 build/build_cli.py

# Run directly without python invocation:
./build/aimlite doctor

Interactive API Documentation Portal (api_docs/)

The full documentation portal is built with React, Vite, and modern styling, featuring interactive paradigm step-by-step guides, code explanation walkthroughs, copy-to-clipboard code blocks, and an API test playground:

cd api_docs
npm install
npm run dev     # Launch local docs dev server at http://localhost:5173
npm run build   # Build production bundle into api_docs/dist/

Testing

AIMLite includes a comprehensive 42-test suite validating CLI commands, header generation, data validation, model lifecycle, inference serving, and end-to-end paradigm workflows:

uv run test        # Core test runner
uv run pytest      # Full pytest runner (42/42 passing)