optimumai 0.1.0__py3-none-any.whl

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/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"]

optimumai/algebra/matrix.py

@@ -0,0 +1,94 @@
+"""Matrices that narrate their own multiplication.
+
+``y = W·x + b`` is every dense layer. ``Q·Kᵀ`` is the attention score matrix.
+Watching a matrix multiply fill in cell by cell is the fastest way to make the
+shape rules (``(m,k) @ (k,n) → (m,n)``) click.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Sequence
+
+import numpy as np
+
+from optimumai.core._fmt import num
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Trace
+
+
+class Matrix:
+    """A 2-D array with an explainable matrix product."""
+
+    def __init__(self, data: Sequence[Sequence[float]] | np.ndarray):
+        self.data = np.asarray(data, dtype=float)
+        if self.data.ndim != 2:
+            raise ValueError(f"Matrix expects 2-D data, got shape {self.data.shape}")
+
+    @property
+    def shape(self) -> tuple[int, int]:
+        return (int(self.data.shape[0]), int(self.data.shape[1]))
+
+    def __repr__(self) -> str:
+        return f"Matrix(shape={self.shape})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Matrix) and np.array_equal(self.data, other.data)
+
+    # ------------------------------------------------------------ matrix product
+    def matmul_trace(self, other: Matrix | Iterable) -> Trace:
+        """Trace ``C = A @ B``, one output cell at a time."""
+        b = other if isinstance(other, Matrix) else Matrix(np.atleast_2d(other))
+        A, B = self.data, b.data
+        if A.shape[1] != B.shape[0]:
+            raise ValueError(
+                f"cannot multiply {A.shape} by {B.shape}: "
+                f"inner dimensions {A.shape[1]} and {B.shape[0]} must match"
+            )
+        m, k = A.shape
+        _, n = B.shape
+        t = Trace(
+            op="matmul",
+            formula="C[i,j] = Σₖ A[i,k]·B[k,j]",
+            complexity=f"O(m·k·n) = O({m}·{k}·{n})",
+            why_ai=[
+                "Every dense/linear layer: y = W·x + b",
+                "Projecting inputs into Q, K, V inside attention",
+                "Composing linear transformations across network layers",
+            ],
+            meta={"a_shape": A.shape, "b_shape": B.shape},
+        )
+        C = np.zeros((m, n))
+        for i in range(m):
+            for j in range(n):
+                terms = [f"{num(A[i, p])}×{num(B[p, j])}" for p in range(k)]
+                val = float(np.dot(A[i, :], B[:, j]))
+                C[i, j] = val
+                t.add(
+                    f"Cell C[{i},{j}]",
+                    f"{' + '.join(terms)} = {num(val)}",
+                    val,
+                    detail=f"row {i} of A · column {j} of B",
+                )
+        t.result = C
+        return t
+
+    def matmul(
+        self,
+        other: Matrix | Iterable,
+        explain: bool = False,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+    ) -> np.ndarray:
+        """Matrix product. Set ``explain=True`` to print the cell-by-cell trace."""
+        t = self.matmul_trace(other)
+        return t.render(level) if explain else t.result
+
+    def __matmul__(self, other: Matrix) -> np.ndarray:
+        return self.matmul(other)
+
+    # ------------------------------------------------------------------ transpose
+    def transpose(self) -> Matrix:
+        return Matrix(self.data.T)
+
+    @property
+    def T(self) -> Matrix:  # noqa: N802 - mirror numpy's attribute name
+        return self.transpose()

optimumai/algebra/vector.py

@@ -0,0 +1,158 @@
+"""Vectors that can explain themselves.
+
+The dot product is the atom of modern AI: it is the similarity between two
+embeddings, the raw attention score ``q · k``, and the inner loop of every
+matrix multiply. Teaching it well pays off everywhere downstream.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+
+from optimumai.core._fmt import num
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Trace
+
+
+class Vector:
+    """A 1-D array with step-by-step explanations of its operations."""
+
+    def __init__(self, data: Iterable[float]):
+        raw = data if isinstance(data, np.ndarray) else list(data)
+        self.data = np.asarray(raw, dtype=float)
+        if self.data.ndim != 1:
+            raise ValueError(f"Vector expects 1-D data, got shape {self.data.shape}")
+
+    # ------------------------------------------------------------------ repr
+    def __len__(self) -> int:
+        return int(self.data.shape[0])
+
+    def __repr__(self) -> str:
+        return f"Vector({self.data.tolist()})"
+
+    def __eq__(self, other: object) -> bool:
+        return isinstance(other, Vector) and np.array_equal(self.data, other.data)
+
+    # ------------------------------------------------------------- dot product
+    def dot_trace(self, other: Vector) -> Trace:
+        """Build the full trace of ``self · other``."""
+        a, b = self.data, self._as_vector(other).data
+        if a.shape != b.shape:
+            raise ValueError(
+                f"dot product needs equal-length vectors, got {a.shape} and {b.shape}"
+            )
+        t = Trace(
+            op="dot",
+            formula="a · b = Σᵢ aᵢ·bᵢ",
+            complexity="O(n)",
+            why_ai=[
+                "Similarity between two embedding vectors",
+                "The raw attention score q · k before scaling",
+                "The inner loop of every matrix multiply and linear layer",
+            ],
+        )
+        products = []
+        for i, (x, y) in enumerate(zip(a, b, strict=True)):
+            p = float(x * y)
+            products.append(p)
+            t.add(f"Multiply component {i}", f"{num(x)} × {num(y)} = {num(p)}", p)
+        total = float(np.sum(products))
+        summation = " + ".join(num(p) for p in products) if products else "0"
+        t.add("Sum the products", f"{summation} = {num(total)}", total)
+        t.result = total
+        return t
+
+    def dot(
+        self,
+        other: Vector,
+        explain: bool = False,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+    ) -> float:
+        """Inner product. Set ``explain=True`` to print the full trace."""
+        t = self.dot_trace(other)
+        return t.render(level) if explain else t.result
+
+    # -------------------------------------------------------------------- norm
+    def norm_trace(self) -> Trace:
+        """Euclidean (L2) norm, ``||a|| = √Σ aᵢ²``."""
+        a = self.data
+        t = Trace(
+            op="norm",
+            formula="||a|| = √(Σᵢ aᵢ²)",
+            complexity="O(n)",
+            why_ai=[
+                "The length of an embedding vector",
+                "Denominator of cosine similarity",
+                "Weight/gradient magnitudes for clipping and regularization",
+            ],
+        )
+        squares = [float(x * x) for x in a]
+        for i, (x, sq) in enumerate(zip(a, squares, strict=True)):
+            t.add(f"Square component {i}", f"{num(x)}² = {num(sq)}", sq)
+        ssum = float(np.sum(squares))
+        t.add("Sum of squares", f"{' + '.join(num(s) for s in squares) or '0'} = {num(ssum)}", ssum)
+        result = float(np.sqrt(ssum))
+        t.add("Square root", f"√{num(ssum)} = {num(result)}", result)
+        t.result = result
+        return t
+
+    def norm(
+        self,
+        explain: bool = False,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+    ) -> float:
+        t = self.norm_trace()
+        return t.render(level) if explain else t.result
+
+    # ---------------------------------------------------------- cosine similarity
+    def cosine_similarity_trace(self, other: Vector) -> Trace:
+        """Cosine similarity ``(a · b) / (||a|| ||b||)`` — the RAG workhorse."""
+        b = self._as_vector(other)
+        if self.data.shape != b.data.shape:
+            raise ValueError(
+                f"cosine similarity needs equal-length vectors, "
+                f"got {self.data.shape} and {b.data.shape}"
+            )
+        t = Trace(
+            op="cosine_similarity",
+            formula="cos(θ) = (a · b) / (||a|| · ||b||)",
+            complexity="O(n)",
+            why_ai=[
+                "Ranking documents against a query in RAG / semantic search",
+                "Measuring how aligned two embeddings are, ignoring magnitude",
+                "Nearest-neighbour lookup in a vector database",
+            ],
+        )
+        dot = float(np.dot(self.data, b.data))
+        na = float(np.linalg.norm(self.data))
+        nb = float(np.linalg.norm(b.data))
+        t.add("Dot product a · b", f"a · b = {num(dot)}", dot)
+        t.add("Norm of a", f"||a|| = {num(na)}", na)
+        t.add("Norm of b", f"||b|| = {num(nb)}", nb)
+        denom = na * nb
+        if denom == 0.0:
+            raise ValueError("cosine similarity is undefined for a zero vector")
+        result = dot / denom
+        t.add(
+            "Divide",
+            f"{num(dot)} / ({num(na)} × {num(nb)}) = {num(result)}",
+            result,
+        )
+        t.result = result
+        return t
+
+    def cosine_similarity(
+        self,
+        other: Vector,
+        explain: bool = False,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+    ) -> float:
+        t = self.cosine_similarity_trace(other)
+        return t.render(level) if explain else t.result
+
+    # ---------------------------------------------------------------- internals
+    @staticmethod
+    def _as_vector(other: Vector | Iterable[float]) -> Vector:
+        return other if isinstance(other, Vector) else Vector(other)

optimumai/cli/main.py

@@ -0,0 +1,150 @@
+"""The ``optimumai`` command-line interface.
+
+Examples:
+    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
+    optimumai learn
+"""
+
+from __future__ import annotations
+
+import ast
+
+import click
+
+from optimumai import __version__
+from optimumai.algebra.matrix import Matrix
+from optimumai.algebra.vector import Vector
+from optimumai.core.explain import ExplainLevel
+from optimumai.probability.softmax import softmax_trace
+from optimumai.transformers.attention import Attention
+
+_LEVEL_CHOICE = click.Choice([lvl.value for lvl in ExplainLevel], case_sensitive=False)
+
+# topic -> (one-line description, zero-arg callable returning a Trace)
+_TOPICS: dict[str, tuple[str, callable]] = {
+    "dot": (
+        "Dot product — similarity and the atom of matrix multiply",
+        lambda: Vector([1, 2, 3]).dot_trace(Vector([4, 5, 6])),
+    ),
+    "cosine": (
+        "Cosine similarity — the RAG / semantic-search ranking score",
+        lambda: Vector([1, 2, 3]).cosine_similarity_trace(Vector([2, 4, 6])),
+    ),
+    "matmul": (
+        "Matrix multiplication — every dense layer, cell by cell",
+        lambda: Matrix([[1, 2], [3, 4]]).matmul_trace(Matrix([[5, 6], [7, 8]])),
+    ),
+    "softmax": (
+        "Softmax — logits into a probability distribution",
+        lambda: softmax_trace([2.0, 1.0, 0.1]),
+    ),
+    "attention": (
+        "Scaled dot-product attention — the transformer core",
+        Attention.demo,
+    ),
+}
+
+
+def _parse_literal(text: str, what: str):
+    try:
+        return ast.literal_eval(text)
+    except (ValueError, SyntaxError) as exc:
+        raise click.BadParameter(
+            f"could not parse {what}: {text!r} (expected e.g. \"[1, 2, 3]\")"
+        ) from exc
+
+
+@click.group(context_settings={"help_option_names": ["-h", "--help"]})
+@click.version_option(__version__, prog_name="optimumai")
+def cli() -> None:
+    """OptimumAI — unlock the math behind AI, one explained step at a time."""
+
+
+# --------------------------------------------------------------------- algebra
+@cli.group()
+def algebra() -> None:
+    """Vector and matrix operations."""
+
+
+@algebra.command("dot")
+@click.argument("a")
+@click.argument("b")
+@click.option("--level", type=_LEVEL_CHOICE, default="intermediate", help="Detail level.")
+def algebra_dot(a: str, b: str, level: str) -> None:
+    """Dot product of two vectors, e.g. optimumai algebra dot "[1,2,3]" "[4,5,6]"."""
+    va = Vector(_parse_literal(a, "vector A"))
+    vb = Vector(_parse_literal(b, "vector B"))
+    va.dot(vb, explain=True, level=level)
+
+
+@algebra.command("cosine")
+@click.argument("a")
+@click.argument("b")
+@click.option("--level", type=_LEVEL_CHOICE, default="intermediate", help="Detail level.")
+def algebra_cosine(a: str, b: str, level: str) -> None:
+    """Cosine similarity of two vectors."""
+    va = Vector(_parse_literal(a, "vector A"))
+    vb = Vector(_parse_literal(b, "vector B"))
+    va.cosine_similarity(vb, explain=True, level=level)
+
+
+@algebra.command("matmul")
+@click.argument("a")
+@click.argument("b")
+@click.option("--level", type=_LEVEL_CHOICE, default="intermediate", help="Detail level.")
+def algebra_matmul(a: str, b: str, level: str) -> None:
+    """Matrix product, e.g. optimumai algebra matmul "[[1,2],[3,4]]" "[[5,6],[7,8]]"."""
+    ma = Matrix(_parse_literal(a, "matrix A"))
+    mb = Matrix(_parse_literal(b, "matrix B"))
+    ma.matmul(mb, explain=True, level=level)
+
+
+# --------------------------------------------------------------------- softmax
+@cli.command("softmax")
+@click.argument("logits")
+@click.option("--temperature", "-t", type=float, default=1.0, help="Sampling temperature (>0).")
+@click.option("--level", type=_LEVEL_CHOICE, default="intermediate", help="Detail level.")
+def softmax_cmd(logits: str, temperature: float, level: str) -> None:
+    """Softmax of a logit vector, e.g. optimumai softmax "[2,1,0.1]"."""
+    values = _parse_literal(logits, "logits")
+    softmax_trace(values, temperature=temperature).render(level)
+
+
+# ------------------------------------------------------------------- attention
+@cli.command("attention")
+@click.option("--demo", "use_demo", is_flag=True, help="Run a built-in 3-token example.")
+@click.option("--seed", type=int, default=0, help="Random seed for --demo.")
+@click.option("--level", type=_LEVEL_CHOICE, default="engineer", help="Detail level.")
+def attention_cmd(use_demo: bool, seed: int, level: str) -> None:
+    """Scaled dot-product attention (currently via the built-in demo)."""
+    if not use_demo:
+        raise click.UsageError("pass --demo to run the built-in attention example")
+    Attention.demo(seed=seed).render(level)
+
+
+# ----------------------------------------------------------------------- learn
+@cli.command("learn")
+@click.argument("topic", required=False)
+@click.option("--level", type=_LEVEL_CHOICE, default="intermediate", help="Detail level.")
+def learn_cmd(topic: str | None, level: str) -> None:
+    """Walk through a topic's math. Run without a topic to list them all."""
+    if topic is None:
+        click.echo("Available topics:\n")
+        for name, (desc, _) in _TOPICS.items():
+            click.echo(f"  {name:<12} {desc}")
+        click.echo('\nTry:  optimumai learn attention --level engineer')
+        return
+    key = topic.lower()
+    if key not in _TOPICS:
+        raise click.BadParameter(
+            f"unknown topic {topic!r}. Choose from: {', '.join(_TOPICS)}"
+        )
+    _, build = _TOPICS[key]
+    build().render(level)
+
+
+if __name__ == "__main__":  # pragma: no cover
+    cli()

optimumai/config.py

@@ -0,0 +1,41 @@
+"""Runtime configuration via environment variables (``OPTIMUMAI_*``).
+
+Follows the workspace convention of ``pydantic-settings`` + ``.env``. Nothing
+here is required for the core math — every field has a sensible default and the
+LLM fields are only consulted by the (optional) tutor layer.
+"""
+
+from __future__ import annotations
+
+from functools import lru_cache
+
+from pydantic_settings import BaseSettings, SettingsConfigDict
+
+from optimumai.core.explain import ExplainLevel
+
+
+class Settings(BaseSettings):
+    """Central settings object, populated from the environment or a ``.env`` file."""
+
+    model_config = SettingsConfigDict(
+        env_prefix="OPTIMUMAI_",
+        env_file=".env",
+        env_file_encoding="utf-8",
+        extra="ignore",
+    )
+
+    # Presentation defaults
+    explain_level: ExplainLevel = ExplainLevel.INTERMEDIATE
+    color: bool = True
+
+    # LLM tutor (optional; used only when the `[llm]` extra is installed)
+    llm_model: str = "gpt-4o-mini"
+    api_key: str | None = None
+    api_base: str | None = None
+    temperature: float = 0.3
+
+
+@lru_cache
+def get_settings() -> Settings:
+    """Return a cached :class:`Settings` instance."""
+    return Settings()

optimumai/core/__init__.py

@@ -0,0 +1,7 @@
+"""Core engine: explain levels, the trace model, and the base op contract."""
+
+from optimumai.core.base_op import BaseOp
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Step, Trace
+
+__all__ = ["BaseOp", "ExplainLevel", "Step", "Trace"]

optimumai/core/_fmt.py

@@ -0,0 +1,40 @@
+"""Small, dependency-light number/array formatting helpers.
+
+Kept in ``core`` so both the math ops (which build human-readable expression
+strings) and the visualization layer can share one formatting convention
+without importing each other.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+import numpy as np
+
+
+def num(x: Any, precision: int = 4) -> str:
+    """Format a scalar compactly: integers stay integers, floats get trimmed."""
+    val = float(x)
+    if val == int(val) and abs(val) < 1e15:
+        return str(int(val))
+    return f"{val:.{precision}g}"
+
+
+def arr(x: Any, precision: int = 4) -> str:
+    """Format a scalar, vector, or matrix as a compact string."""
+    a = np.asarray(x, dtype=float)
+    if a.ndim == 0:
+        return num(float(a), precision)
+    return np.array2string(
+        a,
+        precision=precision,
+        suppress_small=True,
+        separator=", ",
+        floatmode="maxprec",
+    )
+
+
+def shape_of(x: Any) -> str:
+    """Return a short shape label like ``(2, 3)`` or ``scalar``."""
+    a = np.asarray(x)
+    return "scalar" if a.ndim == 0 else str(tuple(a.shape))

optimumai/core/base_op.py

@@ -0,0 +1,58 @@
+"""Base class for composable, explainable operations.
+
+Most simple ops live as methods on :class:`~optimumai.algebra.vector.Vector`
+etc. and just return a :class:`~optimumai.core.trace.Trace`. Multi-stage ops
+(attention, a transformer block, an optimizer step) are cleaner as objects that
+carry configuration, so they subclass :class:`BaseOp`.
+
+The contract is deliberately tiny: implement :meth:`trace` to build a
+:class:`Trace`, and callers get :meth:`run` (fast path) and calling the object
+directly (``op(x, explain=True)``) for free.
+"""
+
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Trace
+
+
+class BaseOp(ABC):
+    """An operation that can compute quietly or explain itself step by step."""
+
+    name: str = "op"
+
+    @abstractmethod
+    def trace(self, *args: Any, **kwargs: Any) -> Trace:
+        """Build and return a full :class:`Trace` for the given inputs."""
+        raise NotImplementedError
+
+    def run(self, *args: Any, **kwargs: Any) -> Any:
+        """Compute and return just the result (no rendering)."""
+        return self.trace(*args, **kwargs).result
+
+    def explain(
+        self,
+        *args: Any,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+        console: Any = None,
+        **kwargs: Any,
+    ) -> Any:
+        """Compute, render the trace, and return the result."""
+        return self.trace(*args, **kwargs).render(level=level, console=console)
+
+    def __call__(
+        self,
+        *args: Any,
+        explain: bool = False,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+        console: Any = None,
+        **kwargs: Any,
+    ) -> Any:
+        """``op(x)`` computes; ``op(x, explain=True)`` also prints the trace."""
+        t = self.trace(*args, **kwargs)
+        if explain:
+            return t.render(level=level, console=console)
+        return t.result

optimumai/core/explain.py

@@ -0,0 +1,46 @@
+"""Explanation verbosity levels.
+
+The same computation can be explained for four audiences. Higher levels do not
+*change* the math — they reveal more of it (formulas, complexity, edge cases).
+"""
+
+from __future__ import annotations
+
+from enum import Enum
+
+
+class ExplainLevel(str, Enum):
+    """How much detail a rendered trace should surface."""
+
+    BEGINNER = "beginner"
+    INTERMEDIATE = "intermediate"
+    ENGINEER = "engineer"
+    RESEARCHER = "researcher"
+
+    @classmethod
+    def parse(cls, value: str | ExplainLevel) -> ExplainLevel:
+        """Coerce a string (case-insensitive) or enum into an ``ExplainLevel``."""
+        if isinstance(value, cls):
+            return value
+        try:
+            return cls(str(value).strip().lower())
+        except ValueError as exc:  # pragma: no cover - defensive
+            valid = ", ".join(level.value for level in cls)
+            raise ValueError(
+                f"Unknown explain level {value!r}. Choose one of: {valid}."
+            ) from exc
+
+    @property
+    def rank(self) -> int:
+        """Ordinal used to gate optional sections (higher shows more)."""
+        order = [
+            ExplainLevel.BEGINNER,
+            ExplainLevel.INTERMEDIATE,
+            ExplainLevel.ENGINEER,
+            ExplainLevel.RESEARCHER,
+        ]
+        return order.index(self)
+
+    def at_least(self, other: ExplainLevel) -> bool:
+        """True when this level is as detailed as ``other`` (or more)."""
+        return self.rank >= other.rank

optimumai/core/trace.py

@@ -0,0 +1,97 @@
+"""The computation trace — the beating heart of OptimumAI.
+
+Every operation, whether a 3-element dot product or a full attention block,
+produces a :class:`Trace`: an ordered list of :class:`Step` objects plus the
+final result and the "why AI cares" context. A trace can be rendered to a
+terminal, inspected programmatically, or asserted against in tests.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+from optimumai.core.explain import ExplainLevel
+
+
+@dataclass
+class Step:
+    """One intermediate move in a computation.
+
+    Attributes:
+        index: 1-based position in the trace.
+        title: Short label, e.g. ``"Multiply component 0"``.
+        expression: Human-readable computation, e.g. ``"1 × 4 = 4"``.
+        value: The numeric result of this step (scalar / vector / matrix).
+        detail: Optional longer note shown at higher explain levels.
+    """
+
+    index: int
+    title: str
+    expression: str
+    value: Any = None
+    detail: str = ""
+
+
+@dataclass
+class Trace:
+    """A complete, replayable record of an operation.
+
+    Attributes:
+        op: Name of the operation, e.g. ``"dot"`` or ``"attention"``.
+        result: The final output value.
+        steps: Ordered intermediate steps.
+        formula: The closed-form formula, e.g. ``"a · b = Σ aᵢbᵢ"``.
+        why_ai: Bullet points on where this shows up in real AI systems.
+        complexity: Big-O note, surfaced at engineer/researcher levels.
+        meta: Free-form extra data (shapes, hyper-params, ...).
+    """
+
+    op: str
+    result: Any = None
+    steps: list[Step] = field(default_factory=list)
+    formula: str = ""
+    why_ai: list[str] = field(default_factory=list)
+    complexity: str = ""
+    meta: dict[str, Any] = field(default_factory=dict)
+
+    def add(
+        self, title: str, expression: str, value: Any = None, detail: str = ""
+    ) -> Trace:
+        """Append a step and return ``self`` for fluent chaining."""
+        self.steps.append(
+            Step(
+                index=len(self.steps) + 1,
+                title=title,
+                expression=expression,
+                value=value,
+                detail=detail,
+            )
+        )
+        return self
+
+    def render(
+        self,
+        level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+        console: Any = None,
+    ) -> Any:
+        """Pretty-print this trace to the terminal and return the result.
+
+        Imported lazily so the math layer never hard-depends on the UI layer.
+        """
+        from optimumai.visualization.terminal import render_trace
+
+        render_trace(self, level=ExplainLevel.parse(level), console=console)
+        return self.result
+
+    def last(self) -> Step:
+        """Return the final recorded step (raises if the trace is empty)."""
+        if not self.steps:
+            raise IndexError("trace has no steps")
+        return self.steps[-1]
+
+    def __len__(self) -> int:
+        return len(self.steps)
+
+    def __iter__(self):
+        return iter(self.steps)

optimumai/probability/__init__.py

@@ -0,0 +1,5 @@
+"""Probability building blocks used across modern AI."""
+
+from optimumai.probability.softmax import softmax, softmax_trace
+
+__all__ = ["softmax", "softmax_trace"]

optimumai/probability/softmax.py

@@ -0,0 +1,83 @@
+"""Softmax — the function that turns raw scores into a distribution.
+
+It is the last layer of a classifier, the thing that makes attention weights sum
+to one, and the knob (via temperature) behind "creative" vs "focused" sampling.
+This implementation uses the standard max-subtraction trick for numerical
+stability and shows *why* that trick is safe.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+import numpy as np
+
+from optimumai.core._fmt import arr, num
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Trace
+
+
+def softmax_trace(x: Iterable[float], temperature: float = 1.0) -> Trace:
+    """Build the full trace of ``softmax(x)`` with an optional temperature."""
+    vec = np.asarray(list(x), dtype=float)
+    if vec.ndim != 1:
+        raise ValueError(f"softmax_trace expects a 1-D input, got shape {vec.shape}")
+    if temperature <= 0:
+        raise ValueError(f"temperature must be > 0, got {temperature}")
+
+    t = Trace(
+        op="softmax",
+        formula="softmax(xᵢ) = e^(xᵢ) / Σⱼ e^(xⱼ)",
+        complexity="O(n)",
+        why_ai=[
+            "Converts logits into a probability distribution that sums to 1",
+            "Produces attention weights from scaled QKᵀ scores",
+            "The final layer for classification and next-token prediction",
+        ],
+        meta={"temperature": temperature},
+    )
+
+    if temperature != 1.0:
+        vec = vec / temperature
+        t.add(
+            "Apply temperature",
+            f"xᵢ / T  with T = {num(temperature)}  →  {arr(vec)}",
+            vec.copy(),
+            detail="T < 1 sharpens the distribution; T > 1 flattens it.",
+        )
+
+    x_max = float(np.max(vec))
+    shifted = vec - x_max
+    t.add(
+        "Subtract the max (stability)",
+        f"xᵢ − {num(x_max)}  →  {arr(shifted)}",
+        shifted,
+        detail="Shifting by a constant leaves softmax unchanged but avoids overflow in e^x.",
+    )
+
+    exps = np.exp(shifted)
+    t.add("Exponentiate", f"e^(xᵢ − max)  →  {arr(exps)}", exps)
+
+    denom = float(np.sum(exps))
+    t.add("Sum the exponentials", f"Σ = {num(denom)}", denom)
+
+    probs = exps / denom
+    t.add(
+        "Normalize",
+        f"e^(xᵢ) / Σ  →  {arr(probs)}",
+        probs,
+        detail=f"Check: the outputs sum to {num(float(np.sum(probs)))}.",
+    )
+    t.result = probs
+    return t
+
+
+def softmax(
+    x: Iterable[float],
+    temperature: float = 1.0,
+    explain: bool = False,
+    level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+) -> np.ndarray:
+    """Return the softmax of ``x``. Set ``explain=True`` to print the trace."""
+    t = softmax_trace(x, temperature=temperature)
+    return t.render(level) if explain else t.result

optimumai/transformers/__init__.py

@@ -0,0 +1,5 @@
+"""Transformer math, explained one stage at a time."""
+
+from optimumai.transformers.attention import Attention
+
+__all__ = ["Attention"]

optimumai/transformers/attention.py

@@ -0,0 +1,117 @@
+"""Scaled dot-product attention — the operation that defines transformers.
+
+    Attention(Q, K, V) = softmax( Q·Kᵀ / √dₖ ) · V
+
+This is where every earlier idea converges: the dot products become the score
+matrix (algebra), ``/√dₖ`` keeps gradients healthy (calculus), softmax turns
+scores into weights (probability), and the final matmul mixes the values. Run it
+with ``explain=True`` to watch all four stages.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from optimumai.core._fmt import arr, num
+from optimumai.core.base_op import BaseOp
+from optimumai.core.trace import Trace
+
+
+def _softmax_rows(x: np.ndarray) -> np.ndarray:
+    """Numerically stable softmax over the last axis (per query row)."""
+    shifted = x - np.max(x, axis=-1, keepdims=True)
+    exps = np.exp(shifted)
+    return exps / np.sum(exps, axis=-1, keepdims=True)
+
+
+class Attention(BaseOp):
+    """Single-head scaled dot-product attention.
+
+    Args:
+        d_k: Key/query dimension used for the ``1/√dₖ`` scaling. If omitted it is
+            inferred from ``Q`` at call time.
+    """
+
+    name = "attention"
+
+    def __init__(self, d_k: int | None = None):
+        self.d_k = d_k
+
+    def trace(self, Q, K, V) -> Trace:  # noqa: N803 - Q/K/V are the standard names
+        Q = np.asarray(Q, dtype=float)
+        K = np.asarray(K, dtype=float)
+        V = np.asarray(V, dtype=float)
+        for name, mat in ("Q", Q), ("K", K), ("V", V):
+            if mat.ndim != 2:
+                raise ValueError(f"{name} must be 2-D (tokens × features), got shape {mat.shape}")
+        if Q.shape[1] != K.shape[1]:
+            raise ValueError(
+                f"Q and K must share the feature dim; got {Q.shape[1]} and {K.shape[1]}"
+            )
+        if K.shape[0] != V.shape[0]:
+            raise ValueError(
+                f"K and V must share the number of tokens; got {K.shape[0]} and {V.shape[0]}"
+            )
+
+        d_k = self.d_k or Q.shape[1]
+        t = Trace(
+            op="attention",
+            formula="Attention(Q,K,V) = softmax(Q·Kᵀ / √dₖ) · V",
+            complexity="O(n²·d) for n tokens of dimension d",
+            why_ai=[
+                "The core operation of every transformer (GPT, BERT, ViT, ...)",
+                "Lets each token gather information from the tokens it finds relevant",
+                "Q = what I'm looking for, K = what I offer, V = what I pass on",
+            ],
+            meta={"d_k": d_k, "q_shape": Q.shape, "k_shape": K.shape, "v_shape": V.shape},
+        )
+
+        scores = Q @ K.T
+        t.add(
+            "Score: Q · Kᵀ",
+            f"raw relevance of every query to every key\n{arr(scores)}",
+            scores,
+            detail="Entry [i,j] is the dot product of query i with key j.",
+        )
+
+        scale = np.sqrt(d_k)
+        scaled = scores / scale
+        t.add(
+            f"Scale by 1/√dₖ = 1/√{d_k}",
+            f"scores / {num(scale)}\n{arr(scaled)}",
+            scaled,
+            detail="Scaling keeps the softmax out of its saturated, low-gradient region.",
+        )
+
+        weights = _softmax_rows(scaled)
+        row_sums = np.sum(weights, axis=-1)
+        t.add(
+            "Softmax over each row",
+            f"attention weights (each row sums to 1)\n{arr(weights)}",
+            weights,
+            detail=f"Row sums = {arr(row_sums)} — every query distributes 100% of its attention.",
+        )
+
+        output = weights @ V
+        t.add(
+            "Weighted sum: weights · V",
+            f"blend value vectors by attention weight\n{arr(output)}",
+            output,
+            detail="Each output row is a convex combination of the value vectors.",
+        )
+        t.result = output
+        return t
+
+    def forward(self, Q, K, V, explain: bool = False, level="intermediate"):  # noqa: N803
+        """Compute attention. Set ``explain=True`` to print the four-stage trace."""
+        t = self.trace(Q, K, V)
+        return t.render(level) if explain else t.result
+
+    @classmethod
+    def demo(cls, seed: int = 0) -> Trace:
+        """A tiny, reproducible 3-token / dₖ=4 example for docs and the CLI."""
+        rng = np.random.default_rng(seed)
+        Q = rng.normal(size=(3, 4)).round(2)
+        K = rng.normal(size=(3, 4)).round(2)
+        V = rng.normal(size=(3, 4)).round(2)
+        return cls(d_k=4).trace(Q, K, V)

optimumai/visualization/__init__.py

@@ -0,0 +1,5 @@
+"""Terminal rendering for computation traces."""
+
+from optimumai.visualization.terminal import render_trace
+
+__all__ = ["render_trace"]

optimumai/visualization/terminal.py

@@ -0,0 +1,88 @@
+"""Render a :class:`~optimumai.core.trace.Trace` to the terminal with Rich.
+
+The visual grammar is intentionally consistent across every operation:
+
+    ┌ formula ┐  →  step table  →  result  →  why AI uses this
+
+so that a dot product and a full attention block feel like the same tool.
+"""
+
+from __future__ import annotations
+
+from typing import Any
+
+from rich.console import Console
+from rich.panel import Panel
+from rich.table import Table
+from rich.text import Text
+
+from optimumai.core._fmt import arr, shape_of
+from optimumai.core.explain import ExplainLevel
+from optimumai.core.trace import Trace
+
+_default_console = Console()
+
+
+def _fmt_step_value(value: Any) -> str:
+    if value is None:
+        return ""
+    text = arr(value)
+    # Multi-line arrays already carry their own layout; keep scalars terse.
+    return text
+
+
+def render_trace(
+    trace: Trace,
+    level: str | ExplainLevel = ExplainLevel.INTERMEDIATE,
+    console: Console | None = None,
+) -> None:
+    """Pretty-print ``trace`` at the requested detail ``level``."""
+    level = ExplainLevel.parse(level)
+    console = console or _default_console
+
+    # ---- Header: name + formula ------------------------------------------
+    header = Text(trace.op.replace("_", " ").upper(), style="bold cyan")
+    if trace.formula:
+        header.append("\n")
+        header.append(trace.formula, style="italic")
+    console.print(Panel(header, border_style="cyan", title="[bold]OptimumAI[/bold]"))
+
+    # ---- Steps table ------------------------------------------------------
+    table = Table(show_lines=True, expand=False, border_style="grey42")
+    table.add_column("#", justify="right", style="dim", no_wrap=True)
+    table.add_column("Step", style="bold")
+    table.add_column("Computation", style="white")
+    if level.at_least(ExplainLevel.ENGINEER):
+        table.add_column("Result", style="green")
+
+    show_detail = level.at_least(ExplainLevel.INTERMEDIATE)
+    for step in trace.steps:
+        computation = step.expression
+        if show_detail and step.detail:
+            computation += f"\n[dim italic]{step.detail}[/dim italic]"
+        row = [str(step.index), step.title, computation]
+        if level.at_least(ExplainLevel.ENGINEER):
+            row.append(_fmt_step_value(step.value))
+        table.add_row(*row)
+    console.print(table)
+
+    # ---- Result -----------------------------------------------------------
+    result_text = arr(trace.result) if trace.result is not None else "—"
+    console.print(
+        Panel(
+            Text(result_text, style="bold green"),
+            title=f"Result  ·  {shape_of(trace.result)}",
+            border_style="green",
+        )
+    )
+
+    # ---- Why AI uses this -------------------------------------------------
+    if trace.why_ai:
+        bullets = "\n".join(f"• {reason}" for reason in trace.why_ai)
+        console.print(
+            Panel(bullets, title="Why AI uses this", border_style="magenta")
+        )
+
+    # ---- Complexity (engineer+) ------------------------------------------
+    if trace.complexity and level.at_least(ExplainLevel.ENGINEER):
+        console.print(Text(f"Complexity: {trace.complexity}", style="dim yellow"))

optimumai-0.1.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,24 @@
+optimumai/__init__.py,sha256=RdLdgZi6-8nxDQw-Uz5ef9yAJy-g36aTunaLxq478xQ,849
+optimumai/config.py,sha256=hjTbdBwGmU2ZTyqwOzxa9IVnO7a8bcxILFJsJVQpudA,1194
+optimumai/algebra/__init__.py,sha256=7I-esC0-DM5eDt-39i9MAyz2fPNJnFJ-JSTbnjdNnbU,174
+optimumai/algebra/matrix.py,sha256=AVmzBj1TnsAmmKHezv1WTY-tbob8PPzo9ZlRzNkPF6E,3412
+optimumai/algebra/vector.py,sha256=rVUsVFBaehrmCjCRM_QEkEBb3UZDAekNjDYyULEJQgQ,6066
+optimumai/cli/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+optimumai/cli/main.py,sha256=WUD-q1LQNSREYbWLSQBM5Hyua2zPe7vwR-cqDVMcqzA,5641
+optimumai/core/__init__.py,sha256=3PysOkzYJ_eBrmPOfaPOK3I5Q2fTGEbJTjz1i3UsVqA,269
+optimumai/core/_fmt.py,sha256=bOEZ63Cii3uPv8U8dUbkVLpwh3zIW4YQ_h1PDYDCSSo,1122
+optimumai/core/base_op.py,sha256=1V2usbw6y-Ut0AuEexEL3Hdd9aDCCKaG-dvwvPOQmQs,1967
+optimumai/core/explain.py,sha256=QuVBoSbTAv6wqAOp59hO5ttmHQPI2TD0mqeJbNVGclQ,1499
+optimumai/core/trace.py,sha256=gumIqCnCWYkUT_PZGboa7ogFqOVGx9R5gf9VvjLQE8Y,3052
+optimumai/probability/__init__.py,sha256=5iY2gxZ0H045qCqBw9R_jdeFyxAm46RhuDHPoW64wxA,163
+optimumai/probability/softmax.py,sha256=ynqZ_SxVEDcuMCkEbmedEfHHWNLvFrsjmUV8w28ZG3I,2756
+optimumai/transformers/__init__.py,sha256=hl3wcjDiUOKnQQ7iDacLQAdNBiA8KHAYCERLRjAGtzU,136
+optimumai/transformers/attention.py,sha256=vZeQAEGRKL6s2QdC_kwkE0jCYYXsJ8IOiDLgKvNjySg,4364
+optimumai/utils/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+optimumai/visualization/__init__.py,sha256=ph9x8U8lY53Q2WlXUz2TqoSTZd3_QOaRIEiOACUxyCY,136
+optimumai/visualization/terminal.py,sha256=l1YfXuAk_9agKnGYZk6SZYPnWY_1sxTREANHpygT9HU,3192
+optimumai-0.1.0.dist-info/METADATA,sha256=8ic742KPGdzIQ9Ph4Rjt1T-8vsAINgmbXIrRskoCu34,6773
+optimumai-0.1.0.dist-info/WHEEL,sha256=mffPy8wBnZQn2VnJUU5jE99KsxaSfiyMHV9Yt0aLVxs,87
+optimumai-0.1.0.dist-info/entry_points.txt,sha256=OFfCnMHQ7JfnW10bCbnMXSJYj7If3jDgu6IY1oGBHZE,53
+optimumai-0.1.0.dist-info/licenses/LICENSE,sha256=e6mPmo0oVijvAFmm8-_9XTjH9xeyYJ1RqK_jYL7tiPo,1072
+optimumai-0.1.0.dist-info/RECORD,,

optimumai-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.30.1
+Root-Is-Purelib: true
+Tag: py3-none-any

optimumai-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+optimumai = optimumai.cli.main:cli

optimumai-0.1.0.dist-info/licenses/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.