aimlite 0.1.0__tar.gz

aimlite-0.1.0/.gitignore

@@ -0,0 +1,20 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+dist/
+wheels/
+*.egg-info
+.pytest_cache/
+
+# Virtual environments
+.venv
+node_modules/
+
+# Build and training artifacts
+artifacts/
+checkpoints/
+experiments/
+models/
+data/
+*.pkl
+.aimlite/

aimlite-0.1.0/.python-version

@@ -0,0 +1 @@
+3.14

aimlite-0.1.0/PKG-INFO

@@ -0,0 +1,230 @@
+Metadata-Version: 2.5
+Name: aimlite
+Version: 0.1.0
+Summary: The Django for AI & Machine Learning — zero-configuration, zero-path execution.
+Author-email: Mickyas Tesfaye <alazartesfaye42@gmail.com>, Beamlak Tadesse <atocodes@gmail.com>
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+
+# AIMLite
+
+**The Django for AI & Machine Learning** — an opinionated, convention-over-configuration Python framework with zero-path CLI execution.
+
+---
+
+## PyPI Installation
+
+```bash
+pip install aimlite
+```
+
+Or with [`uv`](https://docs.astral.sh/uv/):
+```bash
+uv add aimlite
+```
+
+```python
+from aimlite import Model, Dataset, BaseTrainer, BaseConfig, BaseEvaluator, BaseInference
+```
+
+---
+
+## Authors & Collaborators
+
+- **Mickyas Tesfaye** ([alazartesfaye42@gmail.com](mailto:alazartesfaye42@gmail.com))
+- **Beamlak Tadesse** ([atocodes@gmail.com](mailto: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 detects and uses project `.venv` (powered by `uv` or `pip`).
+- **First-Class IDE Typing Headers**: Generates PEP 561 headers and `.aimlite/workspace.json` on project initialization, giving VS Code, Cursor, and PyCharm immediate auto-completion, parameter hints, and docstrings with zero global installs.
+- **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`](https://docs.astral.sh/uv/) (or `pip`).
+
+```bash
+git clone https://github.com/Alazar42/aimlite.git
+cd aimlite
+uv sync
+```
+
+### Essential Commands
+
+```bash
+uv run aimlite --help         # Run AIMLite CLI
+uv run test                   # Run core test suite (41 tests)
+uv run pytest                 # Full pytest runner
+```
+
+---
+
+## Project Structure Conventions
+
+When you run `aimlite init <project_name>` (or `aimlite init .`), AIMLite scaffolds a standardized convention layout:
+
+```text
+my_project/
+├── .aimlite/
+│   └── workspace.json        # IDE workspace configuration
+├── .venv/                    # Project-isolated virtual environment
+├── data/                     # Raw datasets (.csv, .json, .txt, .md)
+├── models/                   # Model architectures and saved weights (*.pkl)
+├── experiments/              # Training run logs and metric snapshots (*.json)
+├── data.py                   # Dataset definitions extending Dataset
+├── model.py                  # Model classes extending Model / RAGModel / AdapterModel
+├── trainer.py                # Training lifecycle hooks extending BaseTrainer
+├── evaluator.py              # Metric benchmarks extending BaseEvaluator
+├── inference.py              # Inference pipeline extending BaseInference
+└── aimlite.json              # Project config, dependencies manifest, and paradigms
+```
+
+---
+
+## The 3 AI Paradigms
+
+AIMLite is architected around the 3 primary modern machine learning paradigms:
+
+### Paradigm 1: Training from Scratch (Customer Churn Classifier)
+
+Bespoke tabular architectures, full optimization loops, and custom weights.
+
+- **Dataset**: Kaggle Telecom Churn Dataset ([Kaggle Source](https://www.kaggle.com/datasets/barun2104/telecom-churn))
+- **Required Dependencies**:
+  ```bash
+  aimlite install scikit-learn pandas
+  # or
+  pip install scikit-learn pandas
+  ```
+- **Example Files**: [`docs/examples/churn_scratch/`](docs/examples/churn_scratch/)
+  - `data.py`: `TelecomChurnDataset(Dataset)` ingesting `data/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**:
+  ```bash
+  # Initialize (new directory or in-place with .)
+  aimlite init churn_model && cd churn_model
+  # Place telecom_churn.csv in data/
+  aimlite data validate
+  aimlite train ChurnClassifier
+  aimlite evaluate ChurnClassifier
+  aimlite serve ChurnClassifier --port 8000
+  ```
+
+---
+
+### Paradigm 2: RAG (Knowledge Base Question Answering)
+
+Ground foundation models in enterprise documents with semantic vector search and zero hallucination.
+
+- **Data Formats**: Markdown (`.md`) or text (`.txt`) documents placed in `data/`.
+- **Required Dependencies**:
+  ```bash
+  aimlite install sentence-transformers numpy
+  # or
+  pip install sentence-transformers numpy
+  ```
+- **Example Files**: [`docs/examples/knowledge_rag/`](docs/examples/knowledge_rag/)
+  - `data.py`: `KnowledgeDocsDataset(Dataset)` chunking documents with `TextSplitter`.
+  - `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**:
+  ```bash
+  aimlite init support_rag && cd support_rag
+  # Place knowledge documents in data/
+  aimlite train SupportDocRAG
+  aimlite serve SupportDocRAG --port 8000
+  ```
+
+---
+
+### Paradigm 3: Fine-Tuning (LoRA & PEFT Adapters)
+
+Parameter-efficient adaptation with lightweight delta checkpoints (~50KB to 50MB instead of 14GB+).
+
+- **Data Formats**: Prompt-response instruction pairs in `data/instructions.json` or `data/instructions.jsonl`.
+- **Required Dependencies**:
+  ```bash
+  aimlite install torch peft
+  # or
+  pip install torch peft
+  ```
+- **Example Files**: [`docs/examples/instruction_adapter/`](docs/examples/instruction_adapter/)
+  - `data.py`: `InstructionDataset(Dataset)` formatting instruction prompt templates.
+  - `model.py`: `LoRAInstructionModel(AdapterModel)` configuring `AdapterConfig(r=8, alpha=16.0)` and freezing foundation weights.
+  - `trainer.py`: `AdapterInstructionTrainer(BaseTrainer)` optimizing low-rank delta matrices.
+  - `inference.py`: `AdapterInference(BaseInference)` executing fine-tuned generations via `POST /predict`.
+- **Workflow**:
+  ```bash
+  aimlite init lora_app && cd lora_app
+  # Place instructions.json in data/
+  aimlite train LoRAInstructionModel
+  aimlite serve LoRAInstructionModel --port 8000
+  ```
+
+---
+
+## Zero-Path CLI Reference
+
+AIMLite provides zero-path convention-over-configuration commands:
+
+| Command | Description |
+|---|---|
+| `aimlite init [project_name \| .]` | Scaffolds a project in a new folder or directly in the current directory (`.`), setting up `.venv`, `.aimlite/workspace.json` IDE headers, starter files, and conventions. |
+| `aimlite install [packages...]` | Without arguments, installs all dependencies listed in `aimlite.json`. With packages, installs them into `.venv` using `uv` (or `pip`) and adds them to `aimlite.json`. |
+| `aimlite data validate` | Validates dataset schema, record count, column names, and partition readiness across all datasets in `data/`. |
+| `aimlite train [ModelName]` | Automatically discovers registered models and executes training. Saves checkpoint to `models/<model_name>.pkl` and snapshots to `experiments/`. |
+| `aimlite evaluate [ModelName]` | Loads the model's checkpoint and calculates benchmark metrics on test partitions. |
+| `aimlite serve [ModelName] [--port 8000] [--frontend <dir>]` | Starts an HTTP inference server exposing `POST /predict`, `GET /health`, `GET /docs`, custom routes, and optional static frontend hosting. |
+| `aimlite doctor` | Diagnoses runtime health, virtual environment, hardware accelerator availability (`cuda`, `mps`, `cpu`), and directory permissions. |
+
+---
+
+## 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:
+
+```bash
+# 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:
+
+```bash
+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 41-test suite validating CLI commands, header generation, data validation, model lifecycle, inference serving, and end-to-end paradigm workflows:
+
+```bash
+uv run test        # Core test runner
+uv run pytest      # Full pytest runner (41/41 passing)
+```

aimlite-0.1.0/README.md

@@ -0,0 +1,222 @@
+# AIMLite
+
+**The Django for AI & Machine Learning** — an opinionated, convention-over-configuration Python framework with zero-path CLI execution.
+
+---
+
+## PyPI Installation
+
+```bash
+pip install aimlite
+```
+
+Or with [`uv`](https://docs.astral.sh/uv/):
+```bash
+uv add aimlite
+```
+
+```python
+from aimlite import Model, Dataset, BaseTrainer, BaseConfig, BaseEvaluator, BaseInference
+```
+
+---
+
+## Authors & Collaborators
+
+- **Mickyas Tesfaye** ([alazartesfaye42@gmail.com](mailto:alazartesfaye42@gmail.com))
+- **Beamlak Tadesse** ([atocodes@gmail.com](mailto: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 detects and uses project `.venv` (powered by `uv` or `pip`).
+- **First-Class IDE Typing Headers**: Generates PEP 561 headers and `.aimlite/workspace.json` on project initialization, giving VS Code, Cursor, and PyCharm immediate auto-completion, parameter hints, and docstrings with zero global installs.
+- **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`](https://docs.astral.sh/uv/) (or `pip`).
+
+```bash
+git clone https://github.com/Alazar42/aimlite.git
+cd aimlite
+uv sync
+```
+
+### Essential Commands
+
+```bash
+uv run aimlite --help         # Run AIMLite CLI
+uv run test                   # Run core test suite (41 tests)
+uv run pytest                 # Full pytest runner
+```
+
+---
+
+## Project Structure Conventions
+
+When you run `aimlite init <project_name>` (or `aimlite init .`), AIMLite scaffolds a standardized convention layout:
+
+```text
+my_project/
+├── .aimlite/
+│   └── workspace.json        # IDE workspace configuration
+├── .venv/                    # Project-isolated virtual environment
+├── data/                     # Raw datasets (.csv, .json, .txt, .md)
+├── models/                   # Model architectures and saved weights (*.pkl)
+├── experiments/              # Training run logs and metric snapshots (*.json)
+├── data.py                   # Dataset definitions extending Dataset
+├── model.py                  # Model classes extending Model / RAGModel / AdapterModel
+├── trainer.py                # Training lifecycle hooks extending BaseTrainer
+├── evaluator.py              # Metric benchmarks extending BaseEvaluator
+├── inference.py              # Inference pipeline extending BaseInference
+└── aimlite.json              # Project config, dependencies manifest, and paradigms
+```
+
+---
+
+## The 3 AI Paradigms
+
+AIMLite is architected around the 3 primary modern machine learning paradigms:
+
+### Paradigm 1: Training from Scratch (Customer Churn Classifier)
+
+Bespoke tabular architectures, full optimization loops, and custom weights.
+
+- **Dataset**: Kaggle Telecom Churn Dataset ([Kaggle Source](https://www.kaggle.com/datasets/barun2104/telecom-churn))
+- **Required Dependencies**:
+  ```bash
+  aimlite install scikit-learn pandas
+  # or
+  pip install scikit-learn pandas
+  ```
+- **Example Files**: [`docs/examples/churn_scratch/`](docs/examples/churn_scratch/)
+  - `data.py`: `TelecomChurnDataset(Dataset)` ingesting `data/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**:
+  ```bash
+  # Initialize (new directory or in-place with .)
+  aimlite init churn_model && cd churn_model
+  # Place telecom_churn.csv in data/
+  aimlite data validate
+  aimlite train ChurnClassifier
+  aimlite evaluate ChurnClassifier
+  aimlite serve ChurnClassifier --port 8000
+  ```
+
+---
+
+### Paradigm 2: RAG (Knowledge Base Question Answering)
+
+Ground foundation models in enterprise documents with semantic vector search and zero hallucination.
+
+- **Data Formats**: Markdown (`.md`) or text (`.txt`) documents placed in `data/`.
+- **Required Dependencies**:
+  ```bash
+  aimlite install sentence-transformers numpy
+  # or
+  pip install sentence-transformers numpy
+  ```
+- **Example Files**: [`docs/examples/knowledge_rag/`](docs/examples/knowledge_rag/)
+  - `data.py`: `KnowledgeDocsDataset(Dataset)` chunking documents with `TextSplitter`.
+  - `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**:
+  ```bash
+  aimlite init support_rag && cd support_rag
+  # Place knowledge documents in data/
+  aimlite train SupportDocRAG
+  aimlite serve SupportDocRAG --port 8000
+  ```
+
+---
+
+### Paradigm 3: Fine-Tuning (LoRA & PEFT Adapters)
+
+Parameter-efficient adaptation with lightweight delta checkpoints (~50KB to 50MB instead of 14GB+).
+
+- **Data Formats**: Prompt-response instruction pairs in `data/instructions.json` or `data/instructions.jsonl`.
+- **Required Dependencies**:
+  ```bash
+  aimlite install torch peft
+  # or
+  pip install torch peft
+  ```
+- **Example Files**: [`docs/examples/instruction_adapter/`](docs/examples/instruction_adapter/)
+  - `data.py`: `InstructionDataset(Dataset)` formatting instruction prompt templates.
+  - `model.py`: `LoRAInstructionModel(AdapterModel)` configuring `AdapterConfig(r=8, alpha=16.0)` and freezing foundation weights.
+  - `trainer.py`: `AdapterInstructionTrainer(BaseTrainer)` optimizing low-rank delta matrices.
+  - `inference.py`: `AdapterInference(BaseInference)` executing fine-tuned generations via `POST /predict`.
+- **Workflow**:
+  ```bash
+  aimlite init lora_app && cd lora_app
+  # Place instructions.json in data/
+  aimlite train LoRAInstructionModel
+  aimlite serve LoRAInstructionModel --port 8000
+  ```
+
+---
+
+## Zero-Path CLI Reference
+
+AIMLite provides zero-path convention-over-configuration commands:
+
+| Command | Description |
+|---|---|
+| `aimlite init [project_name \| .]` | Scaffolds a project in a new folder or directly in the current directory (`.`), setting up `.venv`, `.aimlite/workspace.json` IDE headers, starter files, and conventions. |
+| `aimlite install [packages...]` | Without arguments, installs all dependencies listed in `aimlite.json`. With packages, installs them into `.venv` using `uv` (or `pip`) and adds them to `aimlite.json`. |
+| `aimlite data validate` | Validates dataset schema, record count, column names, and partition readiness across all datasets in `data/`. |
+| `aimlite train [ModelName]` | Automatically discovers registered models and executes training. Saves checkpoint to `models/<model_name>.pkl` and snapshots to `experiments/`. |
+| `aimlite evaluate [ModelName]` | Loads the model's checkpoint and calculates benchmark metrics on test partitions. |
+| `aimlite serve [ModelName] [--port 8000] [--frontend <dir>]` | Starts an HTTP inference server exposing `POST /predict`, `GET /health`, `GET /docs`, custom routes, and optional static frontend hosting. |
+| `aimlite doctor` | Diagnoses runtime health, virtual environment, hardware accelerator availability (`cuda`, `mps`, `cpu`), and directory permissions. |
+
+---
+
+## 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:
+
+```bash
+# 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:
+
+```bash
+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 41-test suite validating CLI commands, header generation, data validation, model lifecycle, inference serving, and end-to-end paradigm workflows:
+
+```bash
+uv run test        # Core test runner
+uv run pytest      # Full pytest runner (41/41 passing)
+```

aimlite-0.1.0/api_docs/.gitignore

@@ -0,0 +1,24 @@
+# Logs
+logs
+*.log
+npm-debug.log*
+yarn-debug.log*
+yarn-error.log*
+pnpm-debug.log*
+lerna-debug.log*
+
+node_modules
+dist
+dist-ssr
+*.local
+
+# Editor directories and files
+.vscode/*
+!.vscode/extensions.json
+.idea
+.DS_Store
+*.suo
+*.ntvs*
+*.njsproj
+*.sln
+*.sw?

aimlite-0.1.0/api_docs/.oxlintrc.json

@@ -0,0 +1,8 @@
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}

aimlite-0.1.0/api_docs/README.md

@@ -0,0 +1,32 @@
+# React + TypeScript + Vite
+
+This template provides a minimal setup to get React working in Vite with HMR and some Oxlint rules.
+
+Currently, two official plugins are available:
+
+- [@vitejs/plugin-react](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react) uses [Oxc](https://oxc.rs)
+- [@vitejs/plugin-react-swc](https://github.com/vitejs/vite-plugin-react/blob/main/packages/plugin-react-swc) uses [SWC](https://swc.rs/)
+
+## React Compiler
+
+The React Compiler is not enabled on this template because of its impact on dev & build performances. To add it, see [this documentation](https://react.dev/learn/react-compiler/installation).
+
+## Expanding the Oxlint configuration
+
+If you are developing a production application, we recommend enabling type-aware lint rules by installing `oxlint-tsgolint` and editing `.oxlintrc.json`:
+
+```json
+{
+  "$schema": "./node_modules/oxlint/configuration_schema.json",
+  "plugins": ["react", "typescript", "oxc"],
+  "options": {
+    "typeAware": true
+  },
+  "rules": {
+    "react/rules-of-hooks": "error",
+    "react/only-export-components": ["warn", { "allowConstantExport": true }]
+  }
+}
+```
+
+See the [Oxlint rules documentation](https://oxc.rs/docs/guide/usage/linter/rules) for the full list of rules and categories.

aimlite-0.1.0/api_docs/index.html

@@ -0,0 +1,18 @@
+<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="UTF-8" />
+    <link rel="icon" type="image/svg+xml" href="data:image/svg+xml,<svg xmlns='http://www.w3.org/2000/svg' viewBox='0 0 24 24' fill='none' stroke='%2300f2fe' stroke-width='2' stroke-linecap='round' stroke-linejoin='round'><polygon points='13 2 3 14 12 14 11 22 21 10 12 10 13 2'/></svg>" />
+    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
+    <title>AIMLite — The Django for Machine Learning & AI | Interactive API & Architecture Docs</title>
+    <meta name="description" content="Official interactive documentation and API explorer for AIMLite: Zero-Path Execution, BYOF framework contracts, automatic .venv package management, and zero-boilerplate ML serving." />
+    <!-- Modern Typography -->
+    <link rel="preconnect" href="https://fonts.googleapis.com">
+    <link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
+    <link href="https://fonts.googleapis.com/css2?family=Fira+Code:wght@400;500;600&family=Inter:wght@300;400;500;600;700&family=Outfit:wght@400;500;600;700;800&display=swap" rel="stylesheet">
+  </head>
+  <body>
+    <div id="root"></div>
+    <script type="module" src="/src/main.tsx"></script>
+  </body>
+</html>