optimumai 0.1.0__tar.gz

optimumai-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,33 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      fail-fast: false
+      matrix:
+        python-version: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      # setup-uv already creates and activates a .venv (VIRTUAL_ENV is set),
+      # so install straight into it — no explicit `uv venv` needed.
+      - name: Install project
+        run: uv pip install -e ".[dev]"
+
+      - name: Lint
+        run: uv run ruff check src tests
+
+      - name: Test
+        run: uv run pytest --cov=optimumai --cov-report=term-missing

optimumai-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,42 @@
+name: Publish to PyPI
+
+# Publishes on a GitHub Release. Uses PyPI Trusted Publishing (OIDC) — no API
+# token required. One-time setup on PyPI: add a trusted publisher pointing at
+# this repo + workflow (owner: muhammadyahiya, repo: optimumai,
+# workflow: publish.yml, environment: pypi).
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - name: Install uv
+        uses: astral-sh/setup-uv@v5
+      - name: Build sdist and wheel
+        run: uv build
+      - name: Upload artifacts
+        uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish:
+    needs: build
+    runs-on: ubuntu-latest
+    environment:
+      name: pypi
+      url: https://pypi.org/project/optimumai/
+    permissions:
+      id-token: write  # required for trusted publishing
+    steps:
+      - name: Download artifacts
+        uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

optimumai-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+.eggs/
+build/
+dist/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+
+# Tooling
+.pytest_cache/
+.ruff_cache/
+.mypy_cache/
+.coverage
+htmlcov/
+coverage.xml
+
+# Environment / secrets
+.env
+.env.*
+!.env.example
+
+# OS / editor
+.DS_Store
+.idea/
+.vscode/

optimumai-0.1.0/CHANGELOG.md

@@ -0,0 +1,30 @@
+# Changelog
+
+All notable changes to OptimumAI are documented here. The format follows
+[Keep a Changelog](https://keepachangelog.com/), and the project adheres to
+[Semantic Versioning](https://semver.org/).
+
+## [0.1.0] — 2026-07-03
+
+The first release ships the spine of the SDK: the tracer engine plus the full
+arc from a dot product to transformer attention, each runnable with
+`explain=True`.
+
+### Added
+
+- **core** — `Trace`/`Step` computation-trace model, `ExplainLevel`
+  (beginner → intermediate → engineer → researcher), and the `BaseOp` contract.
+- **algebra** — `Vector` (`dot`, `norm`, `cosine_similarity`) and `Matrix`
+  (`matmul`, transpose), each producing a step-by-step trace.
+- **probability** — `softmax` with temperature control and the
+  numerically-stable max-subtraction trick, explained.
+- **transformers** — single-head scaled dot-product `Attention`,
+  `softmax(QKᵀ/√dₖ)·V`, traced across all four stages.
+- **visualization** — Rich terminal renderer with a consistent visual grammar.
+- **cli** — the `optimumai` command: `algebra dot|matmul|cosine`, `softmax`,
+  `attention --demo`, and `learn`.
+- Tooling: hatchling build, pytest suite (40 tests, 91% coverage), ruff, a
+  GitHub Actions CI matrix (Python 3.10–3.13), and a PyPI trusted-publishing
+  workflow.
+
+[0.1.0]: https://github.com/muhammadyahiya/optimumai/releases/tag/v0.1.0

optimumai-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Muhammad Yahiya
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

optimumai-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: optimumai
+Version: 0.1.0
+Summary: Unlock the math behind AI — run any operation with explain=True for a step-by-step trace, terminal visualization, and the intuition of why AI uses it.
+Project-URL: Homepage, https://github.com/muhammadyahiya/optimumai
+Project-URL: Repository, https://github.com/muhammadyahiya/optimumai
+Project-URL: Issues, https://github.com/muhammadyahiya/optimumai/issues
+Author: Muhammad Yahiya
+License: MIT
+License-File: LICENSE
+Keywords: ai,attention,deep-learning,education,explainable,machine-learning,mathematics,transformers,tutorial
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Education
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Education
+Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
+Requires-Python: >=3.10
+Requires-Dist: click>=8.1
+Requires-Dist: numpy>=1.26
+Requires-Dist: pydantic-settings>=2.0
+Requires-Dist: python-dotenv>=1.0
+Requires-Dist: rich>=13.0
+Provides-Extra: dev
+Requires-Dist: pytest-cov>=5.0; extra == 'dev'
+Requires-Dist: pytest>=8.0; extra == 'dev'
+Requires-Dist: ruff>=0.5; extra == 'dev'
+Provides-Extra: llm
+Requires-Dist: litellm>=1.0; extra == 'llm'
+Provides-Extra: viz
+Requires-Dist: matplotlib>=3.8; extra == 'viz'
+Requires-Dist: plotext>=5.2; extra == 'viz'
+Description-Content-Type: text/markdown
+
+# OptimumAI
+
+**Unlock the math behind AI.**
+
+Every mathematical operation in modern AI — from a dot product to a full
+attention block — can be run with `explain=True` to produce a **step-by-step
+computation trace**, a **terminal visualization**, and the intuition for **why
+AI actually uses it**.
+
+The same code runs fast in production *or* teaches you exactly what it's doing.
+micrograd shows you scalar backprop; EpyNN walks you through MLPs — OptimumAI
+gives you a single, traceable API that runs the whole way from `a · b` up to
+`softmax(QKᵀ/√dₖ)·V`.
+
+```python
+from optimumai import Vector
+
+Vector([1, 2, 3]).dot(Vector([4, 5, 6]), explain=True)
+```
+
+```
+╭───────────────────────── OptimumAI ──────────────────────────╮
+│ DOT                                                           │
+│ a · b = Σᵢ aᵢ·bᵢ                                              │
+╰───────────────────────────────────────────────────────────────╯
+ #  Step                 Computation
+ 1  Multiply component 0 1 × 4 = 4
+ 2  Multiply component 1 2 × 5 = 10
+ 3  Multiply component 2 3 × 6 = 18
+ 4  Sum the products     4 + 10 + 18 = 32
+╭──────── Result · scalar ────────╮
+│ 32                              │
+╰─────────────────────────────────╯
+╭──────────── Why AI uses this ────────────╮
+│ • Similarity between two embedding vectors │
+│ • The raw attention score q · k            │
+│ • The inner loop of every matrix multiply  │
+╰────────────────────────────────────────────╯
+```
+
+---
+
+## Install
+
+```bash
+pip install optimumai
+```
+
+Optional extras:
+
+```bash
+pip install "optimumai[llm]"   # LLM tutor (Q&A over concepts)
+pip install "optimumai[viz]"   # extra plotting backends
+```
+
+## Quickstart — Python
+
+```python
+from optimumai import Vector, Matrix, softmax, Attention
+
+# Linear algebra
+Vector([1, 2, 3]).cosine_similarity(Vector([2, 4, 6]), explain=True)   # → 1.0
+Matrix([[1, 2], [3, 4]]).matmul(Matrix([[5, 6], [7, 8]]), explain=True)
+
+# Probability
+softmax([2.0, 1.0, 0.1], temperature=0.5, explain=True)
+
+# Transformers — the headline
+Attention(d_k=4).forward(Q, K, V, explain=True)
+```
+
+Every `explain=True` call returns the numeric result *and* prints the trace, so
+it drops straight into notebooks, scripts, and tests. Prefer the data over the
+print-out? Use the `*_trace` variants:
+
+```python
+trace = Vector([1, 2, 3]).dot_trace(Vector([4, 5, 6]))
+trace.result      # 32.0
+trace.steps       # [Step(...), Step(...), ...]
+trace.why_ai      # ['Similarity between two embedding vectors', ...]
+```
+
+## Quickstart — CLI
+
+```bash
+optimumai algebra dot "[1,2,3]" "[4,5,6]"
+optimumai algebra matmul "[[1,2],[3,4]]" "[[5,6],[7,8]]"
+optimumai softmax "[2,1,0.1]" --temperature 0.5
+optimumai attention --demo --level engineer
+optimumai learn                       # list every topic
+optimumai learn attention --level researcher
+```
+
+## Explain levels
+
+The same math, revealed for four audiences (`--level` on the CLI, `level=` in
+Python):
+
+| Level          | Adds                                              |
+| -------------- | ------------------------------------------------- |
+| `beginner`     | The steps and plain-English "why"                 |
+| `intermediate` | Per-step detail notes (default)                   |
+| `engineer`     | Intermediate values + complexity                  |
+| `researcher`   | Everything                                        |
+
+## What's inside
+
+```
+optimumai/
+├── core/            # Tracer, Step/Trace model, ExplainLevel, BaseOp
+├── algebra/         # Vector (dot, norm, cosine), Matrix (matmul)
+├── probability/     # softmax (with temperature + stability)
+├── transformers/    # scaled dot-product Attention
+├── visualization/   # Rich terminal renderer
+└── cli/             # the `optimumai` command
+```
+
+## Roadmap
+
+`v0.1` ships the spine — algebra → probability → attention — plus the tracer,
+CLI, and terminal visualization. Next up:
+
+- **Calculus & optimization** — derivatives, gradients, SGD/Adam convergence
+- **Neural networks** — dense layers, activations, full backprop trace
+- **Multi-head attention, positional encoding, a full transformer block**
+- **Embeddings, RAG pipeline traces, diffusion schedules**
+- **LLM tutor** — `Tutor().ask("Why is LayerNorm after attention?")`
+- **Streamlit explorer** for visual, interactive pipelines
+
+## Development
+
+```bash
+git clone https://github.com/muhammadyahiya/optimumai
+cd optimumai
+uv venv && uv pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © 2026 Muhammad Yahiya

optimumai-0.1.0/README.md

@@ -0,0 +1,141 @@
+# OptimumAI
+
+**Unlock the math behind AI.**
+
+Every mathematical operation in modern AI — from a dot product to a full
+attention block — can be run with `explain=True` to produce a **step-by-step
+computation trace**, a **terminal visualization**, and the intuition for **why
+AI actually uses it**.
+
+The same code runs fast in production *or* teaches you exactly what it's doing.
+micrograd shows you scalar backprop; EpyNN walks you through MLPs — OptimumAI
+gives you a single, traceable API that runs the whole way from `a · b` up to
+`softmax(QKᵀ/√dₖ)·V`.
+
+```python
+from optimumai import Vector
+
+Vector([1, 2, 3]).dot(Vector([4, 5, 6]), explain=True)
+```
+
+```
+╭───────────────────────── OptimumAI ──────────────────────────╮
+│ DOT                                                           │
+│ a · b = Σᵢ aᵢ·bᵢ                                              │
+╰───────────────────────────────────────────────────────────────╯
+ #  Step                 Computation
+ 1  Multiply component 0 1 × 4 = 4
+ 2  Multiply component 1 2 × 5 = 10
+ 3  Multiply component 2 3 × 6 = 18
+ 4  Sum the products     4 + 10 + 18 = 32
+╭──────── Result · scalar ────────╮
+│ 32                              │
+╰─────────────────────────────────╯
+╭──────────── Why AI uses this ────────────╮
+│ • Similarity between two embedding vectors │
+│ • The raw attention score q · k            │
+│ • The inner loop of every matrix multiply  │
+╰────────────────────────────────────────────╯
+```
+
+---
+
+## Install
+
+```bash
+pip install optimumai
+```
+
+Optional extras:
+
+```bash
+pip install "optimumai[llm]"   # LLM tutor (Q&A over concepts)
+pip install "optimumai[viz]"   # extra plotting backends
+```
+
+## Quickstart — Python
+
+```python
+from optimumai import Vector, Matrix, softmax, Attention
+
+# Linear algebra
+Vector([1, 2, 3]).cosine_similarity(Vector([2, 4, 6]), explain=True)   # → 1.0
+Matrix([[1, 2], [3, 4]]).matmul(Matrix([[5, 6], [7, 8]]), explain=True)
+
+# Probability
+softmax([2.0, 1.0, 0.1], temperature=0.5, explain=True)
+
+# Transformers — the headline
+Attention(d_k=4).forward(Q, K, V, explain=True)
+```
+
+Every `explain=True` call returns the numeric result *and* prints the trace, so
+it drops straight into notebooks, scripts, and tests. Prefer the data over the
+print-out? Use the `*_trace` variants:
+
+```python
+trace = Vector([1, 2, 3]).dot_trace(Vector([4, 5, 6]))
+trace.result      # 32.0
+trace.steps       # [Step(...), Step(...), ...]
+trace.why_ai      # ['Similarity between two embedding vectors', ...]
+```
+
+## Quickstart — CLI
+
+```bash
+optimumai algebra dot "[1,2,3]" "[4,5,6]"
+optimumai algebra matmul "[[1,2],[3,4]]" "[[5,6],[7,8]]"
+optimumai softmax "[2,1,0.1]" --temperature 0.5
+optimumai attention --demo --level engineer
+optimumai learn                       # list every topic
+optimumai learn attention --level researcher
+```
+
+## Explain levels
+
+The same math, revealed for four audiences (`--level` on the CLI, `level=` in
+Python):
+
+| Level          | Adds                                              |
+| -------------- | ------------------------------------------------- |
+| `beginner`     | The steps and plain-English "why"                 |
+| `intermediate` | Per-step detail notes (default)                   |
+| `engineer`     | Intermediate values + complexity                  |
+| `researcher`   | Everything                                        |
+
+## What's inside
+
+```
+optimumai/
+├── core/            # Tracer, Step/Trace model, ExplainLevel, BaseOp
+├── algebra/         # Vector (dot, norm, cosine), Matrix (matmul)
+├── probability/     # softmax (with temperature + stability)
+├── transformers/    # scaled dot-product Attention
+├── visualization/   # Rich terminal renderer
+└── cli/             # the `optimumai` command
+```
+
+## Roadmap
+
+`v0.1` ships the spine — algebra → probability → attention — plus the tracer,
+CLI, and terminal visualization. Next up:
+
+- **Calculus & optimization** — derivatives, gradients, SGD/Adam convergence
+- **Neural networks** — dense layers, activations, full backprop trace
+- **Multi-head attention, positional encoding, a full transformer block**
+- **Embeddings, RAG pipeline traces, diffusion schedules**
+- **LLM tutor** — `Tutor().ask("Why is LayerNorm after attention?")`
+- **Streamlit explorer** for visual, interactive pipelines
+
+## Development
+
+```bash
+git clone https://github.com/muhammadyahiya/optimumai
+cd optimumai
+uv venv && uv pip install -e ".[dev]"
+pytest
+```
+
+## License
+
+MIT © 2026 Muhammad Yahiya

optimumai-0.1.0/examples/quickstart.py

@@ -0,0 +1,31 @@
+"""OptimumAI quickstart — the full arc, from a dot product to attention.
+
+Run me:  python examples/quickstart.py
+"""
+
+import numpy as np
+
+from optimumai import Attention, Matrix, Vector, softmax
+
+
+def main() -> None:
+    print("\n### 1. Dot product — similarity & the atom of matmul ###")
+    Vector([1, 2, 3]).dot(Vector([4, 5, 6]), explain=True)
+
+    print("\n### 2. Cosine similarity — the RAG ranking score ###")
+    Vector([1, 2, 3]).cosine_similarity(Vector([2, 4, 6]), explain=True)
+
+    print("\n### 3. Matrix multiply — every dense layer, cell by cell ###")
+    Matrix([[1, 2], [3, 4]]).matmul(Matrix([[5, 6], [7, 8]]), explain=True)
+
+    print("\n### 4. Softmax — logits into a probability distribution ###")
+    softmax([2.0, 1.0, 0.1], temperature=0.5, explain=True)
+
+    print("\n### 5. Attention — softmax(QKᵀ/√dₖ)·V, the transformer core ###")
+    rng = np.random.default_rng(0)
+    Q, K, V = (rng.normal(size=(3, 4)).round(2) for _ in range(3))
+    Attention(d_k=4).forward(Q, K, V, explain=True, level="engineer")
+
+
+if __name__ == "__main__":
+    main()

optimumai-0.1.0/pyproject.toml

@@ -0,0 +1,76 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "optimumai"
+dynamic = ["version"]
+description = "Unlock the math behind AI — run any operation with explain=True for a step-by-step trace, terminal visualization, and the intuition of why AI uses it."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Muhammad Yahiya" }]
+keywords = [
+    "ai",
+    "machine-learning",
+    "deep-learning",
+    "education",
+    "mathematics",
+    "transformers",
+    "attention",
+    "explainable",
+    "tutorial",
+]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Education",
+    "Intended Audience :: Developers",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Topic :: Scientific/Engineering :: Artificial Intelligence",
+    "Topic :: Education",
+]
+dependencies = [
+    "numpy>=1.26",
+    "rich>=13.0",
+    "click>=8.1",
+    "pydantic-settings>=2.0",
+    "python-dotenv>=1.0",
+]
+
+[project.optional-dependencies]
+llm = ["litellm>=1.0"]
+viz = ["plotext>=5.2", "matplotlib>=3.8"]
+dev = ["pytest>=8.0", "pytest-cov>=5.0", "ruff>=0.5"]
+
+[project.scripts]
+optimumai = "optimumai.cli.main:cli"
+
+[project.urls]
+Homepage = "https://github.com/muhammadyahiya/optimumai"
+Repository = "https://github.com/muhammadyahiya/optimumai"
+Issues = "https://github.com/muhammadyahiya/optimumai/issues"
+
+[tool.hatch.version]
+path = "src/optimumai/__init__.py"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/optimumai"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+addopts = "-q"
+
+[tool.ruff]
+line-length = 100
+target-version = "py310"
+
+[tool.ruff.lint]
+select = ["E", "F", "I", "N", "UP", "B"]
+# Uppercase names (Q, K, V, A, B, W, ...) are standard mathematical notation here.
+ignore = ["N803", "N806"]

optimumai-0.1.0/src/optimumai/__init__.py

@@ -0,0 +1,31 @@
+"""OptimumAI — unlock the math behind AI.
+
+Every operation, from a dot product to a full attention block, can be run with
+``explain=True`` to produce a step-by-step computation trace, a terminal
+visualization, and the context for *why* AI uses it.
+
+    >>> from optimumai import Vector
+    >>> Vector([1, 2, 3]).dot(Vector([4, 5, 6]), explain=True)
+    32.0
+"""
+
+from optimumai.algebra.matrix import Matrix
+from optimumai.algebra.vector import Vector
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Step, Trace
+from optimumai.probability.softmax import softmax, softmax_trace
+from optimumai.transformers.attention import Attention
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "Attention",
+    "ExplainLevel",
+    "Matrix",
+    "Step",
+    "Trace",
+    "Vector",
+    "softmax",
+    "softmax_trace",
+    "__version__",
+]

optimumai-0.1.0/src/optimumai/algebra/__init__.py

@@ -0,0 +1,6 @@
+"""Linear algebra with step-by-step explanations."""
+
+from optimumai.algebra.matrix import Matrix
+from optimumai.algebra.vector import Vector
+
+__all__ = ["Matrix", "Vector"]