Why Aion v0.2.0 matters

Aion started as a focused toolkit for reproducible research primitives—maths, algorithms, visualization, embeddings, and evaluation. With v0.1.9, we deepened that core: remote LLM providers, tool loops, RAG helpers, layered config, native fast_* ops, and the NumPy-based Former transformer.

v0.2.0 (released 2026-07-22) is a different kind of release. It keeps everything that made 0.1.9 useful, then expands Aion into a full research library: classical physics, astronomy, computer vision, a NumPy-first ML stack, caching, serving, databases, experiment tracking, LLM evaluation helpers, and a local Hub.

This post is a deep dive: design goals, what shipped, how it compares to v0.1.9, upgrade and extras, many copy-ready examples, CLI workflows, bug fixes, migration guidance, and what we deliberately deferred.

Who this release is for

v0.2.0 is aimed at people who already live in notebooks and small research repos:

• Students and TAs who need clear, auditable helpers for maths, classical physics, and introductory ML without standing up a full deep-learning stack.
• Lab engineers who want one import surface for RAG/providers (from 0.1.9) plus vision, data loaders, and experiment tracking.
• Independent researchers who prefer optional extras over a monolithic dependency graph—install core first, add [vision], [serve], or [db] when needed.

If you need production training at cluster scale, keep PyTorch/JAX/TF as your training engine. Aion sits beside those tools: shorter glue code, clearer experiments, and science utilities that stay readable in a paper appendix.

Design principles (unchanged)

A few rules still guide every module:

1. Stateless where possible — prefer pure functions and small classes over hidden global state.
2. Transparent defaults — NumPy-first; optional C++ or third-party backends advertise themselves (using_native_extension(), aion doctor).
3. Layered install — core stays lean; extras opt into OpenCV, FastAPI, Gradio, database drivers, and so on.
4. One import brand — from aion.… matches docs module IDs on aqwelai.xyz/docs/aion.

v0.2.0 stretches the scope of those principles; it does not abandon them.

What is new in v0.2.0

Science toolkits

• aion.physics — mechanics, kinematics, thermo, electromagnetism, optics, relativity, integrators, constraints/units, and a lightweight natural-language query router (solve_physics_query). Optional C++ acceleration and a small web dashboard. CLI: aion physics.
• aion.universe — coordinates, observing, orbits, cosmology, catalogs (bright stars, Messier, planets), magnitudes, and time helpers (now_jd, GMST/LST). CLI: aion universe. Optional native path.

Together they support classroom demos and lightweight research notebooks without pulling in full astrophysics frameworks.

Vision and core ML

• aion.vision — classic computer vision on NumPy arrays: I/O, transforms, color, filters, draw, metrics (MSE/PSNR/SSIM), OpenCV-backed morphology and contours. Extra: pip install "aqwel-aion[vision]" (Pillow + opencv-python-headless).
• aion.preprocessing — scalers, encoders, imputers, polynomial features, and related transformers.
• aion.models — classical estimators (linear/logistic regression, KNN, trees, Naive Bayes, KMeans, PCA, pipelines, save/load).
• aion.metrics — classification, regression, clustering, ranking, and NLP-oriented scores.
• aion.hyperopt — cross-validation helpers, grid/random/Bayesian search, early stopping.

Data, structure, and pipelines

• aion.data — CSV/JSON/JSONL loaders and writers, train/val/test splits, text augmentation, schema validation (restored after the 0.1.9 trim).
• aion.datasets — built-in benchmarks and generators (load_iris, moons/blobs, sentiment, NER samples, make_* factories, file readers).
• aion.tokenizer — BPETokenizer, WordPieceTokenizer, Vocabulary.
• aion.pipeline — step-based pipelines (MapStep, FilterStep, BatchStep, …) with retry / fallback / timing.
• aion.structures — Trie, Bloom filter, LRU, heaps, priority queue, Union-Find.

Platform services

• aion.cache — MemoryCache, DiskCache, LLMCache, and @cached with TTL.
• aion.store — SQLite key-value, persistent vector store, chat history.
• aion.tracker / aion.experiments — Tracker / Run, compare helpers, Experiment, BenchmarkSuite, manifests.
• aion.llm_eval — semantic similarity, faithfulness/groundedness, toxicity/PII checks, cost tracking.
• aion.serve — FastAPI /chat, /rag, /health ([serve]).
• aion.db — unified SQLite plus optional MySQL/Postgres/Mongo/Redis ([db]).
• aion.ui / Hub — aion start, HTML reports, optional Gradio/Streamlit ([ui]).
• aion.usage, aion.monitor, aion.doctor, aion.bench — token/cost dashboards, CPU/RAM/disk/GPU snapshots, environment checks, reproducibility helpers.

Install splash and aion welcome round out the developer experience after upgrade.

New optional extras

[serve], [db], [universe], [physics], [vision], [ui], [monitor], and related groups. [full] pulls a broad research stack including the vision OpenCV path.

Deferred / not in this wheel

Terminal coding agents (aion agent, browser UI, IDE bridge), aion.agents (ReAct / multi-agent), and aion api / aion auth are coming soon—CLI stubs or archived sources only. Do not plan production work on those surfaces for 0.2.0.

Bug fixes carried in 0.2.0

• Restored / corrected matrix_transpose, matrix_multiply, z_score_normalization, min_max_scaling in aion.algorithms.arrays.
• Fixed a_star and pagerank import name mismatches in aion.algorithms.__init__.

What you still get from v0.1.9

v0.2.0 does not drop the previous release surface:

Think of 0.2.0 as 0.1.9 plus a research campus, not a breaking rewrite.

Compare: v0.1.9 vs v0.2.0

Install and upgrade

Core

pip install -U "aqwel-aion>=0.2.0"

Useful extras

pip install "aqwel-aion[vision]"    # Pillow + OpenCV headless
pip install "aqwel-aion[serve]"     # FastAPI / uvicorn
pip install "aqwel-aion[db]"        # MySQL / Postgres / Mongo / Redis drivers
pip install "aqwel-aion[ui]"        # Gradio / Streamlit launchers
pip install "aqwel-aion[monitor]"   # psutil / GPU helpers for monitor
pip install "aqwel-aion[physics]"   # physics plotting extras where needed
pip install "aqwel-aion[universe]"  # astronomy plotting extras where needed
pip install "aqwel-aion[full]"      # broad research stack including vision

Verify the install

aion doctor
aion welcome
python -c "import aion; print(aion.__version__)"

aion doctor reports Python version, numpy, optional extras, tracker write access, and whether native C++ backends are available.

Recommended learning path

1. Upgrade and run aion doctor.
2. Skim docs v0.2.0—new modules are marked New and listed first.
3. Run one science snippet (physics or universe) and one ML snippet (iris path below).
4. If you used 0.1.9 RAG/providers, confirm those imports still work, then try aion.llm_eval or aion.cache beside them.
5. Optionally launch Hub with aion start for an interactive tour.

Code: physics

Natural-language routing for common classical tasks, plus explicit simulations:

from aion.physics import solve_physics_query, simulate_pendulum, simulate_spring_mass

result = solve_physics_query("kinetic energy mass=2 velocity=3")
print(result.output_value)  # 9.0

pendulum = simulate_pendulum(1.0, 0.2, steps=100)
print(pendulum.summary["small_angle_period_s"])

spring = simulate_spring_mass(1.0, 10.0, x0=0.1, v0=0, steps=200)
print(len(spring.trajectory))

List supported NL tasks:

from aion.physics import supported_physics_tasks

print(supported_physics_tasks())

CLI:

aion physics --help

Code: universe

Observing helpers, time, and coordinates for lightweight astronomy workflows:

from aion.universe import (
    equatorial_to_horizontal,
    moon_phase,
    moon_illumination,
    now_jd,
    Cosmology,
    load_bright_stars,
)

jd = now_jd()
alt, az = equatorial_to_horizontal(6.75, -16.7, 40.0, 44.5, jd)
print(alt, az)
print(moon_phase(jd), moon_illumination(jd))

cosmo = Cosmology()
print(cosmo.comoving_distance_mpc(0.5))

stars = load_bright_stars()
print(len(stars))

Code: vision

Classic CV on arrays (not plotting—that remains aion.visualization):

from aion.vision import read_image, to_gray, canny, resize, write_image, ssim

img = read_image("photo.png")
small = resize(img, width=256, height=256)
edges = canny(to_gray(small))
write_image("edges.png", edges)
print(ssim(to_gray(small), to_gray(small)))

Install the vision extra first if Pillow / OpenCV are not already available:

pip install "aqwel-aion[vision]"

Code: core ML path

A small end-to-end classification loop with built-in data:

from aion.datasets import load_iris, train_test_split_dataset
from aion.preprocessing import StandardScaler
from aion.models import LogisticRegression
from aion.metrics import accuracy_score, classification_report

ds = load_iris()
train, test = train_test_split_dataset(ds, test_ratio=0.2, seed=42)
scaler = StandardScaler().fit(train.X)
X_train = scaler.transform(train.X)
X_test = scaler.transform(test.X)

model = LogisticRegression().fit(X_train, train.y)
preds = model.predict(X_test)
print(accuracy_score(test.y, preds))
print(classification_report(test.y, preds))

Hyperparameter search

from aion.hyperopt import GridSearch, cross_val_score

scores = cross_val_score(model, X_train, train.y, cv=5)
print(scores)

param_grid = {"C": [0.1, 1.0, 10.0]}
gs = GridSearch(LogisticRegression(), param_grid).fit(X_train, train.y)
print(gs.best_params_, gs.best_score_)

Docs cover Hyperopt (grid/random/Bayesian, early stopping) and Models for the full estimator list.

Code: cache and LLM eval

Reuse expensive calls and score generations without leaving the Aion namespace:

from aion.cache import MemoryCache, cached
from aion.llm_eval import semantic_similarity, toxicity_check, CostTracker

cache = MemoryCache(ttl=60)
cache.set("greeting", "hello")
print(cache.get("greeting"))

@cached(ttl=30)
def expensive(x):
    return x * 2

print(expensive(21))

print(semantic_similarity("Paris is in France", "Paris is the capital of France"))
print(toxicity_check("Have a wonderful day"))

costs = CostTracker()
costs.add(tokens=1200, price_per_1k=0.002)

These pair naturally with the v0.1.9 providers / tools / rag stack you may already use.

Code: carry-forward RAG sketch (still valid)

from aion.rag import chunk_text, MemoryVectorStore, SimpleRAGIndex

chunks = chunk_text("Aion v0.2.0 expands science and ML tooling.", max_chars=64, overlap=8)
store = MemoryVectorStore()
# Wire your embed_fn, then:
# index = SimpleRAGIndex(embed_fn, store)
# index.add(chunks)

Providers and tool loops from 0.1.9 remain the right path for multi-turn assistant work; 0.2.0 adds evaluation and caching around that loop.

CLI workflows worth knowing

Hub dashboard

aion start

Opens a local Hub for library info, module browsing, dependency status, and snippet runs (default http://127.0.0.1:3000).

Science and ops

aion physics --help
aion universe --help
aion vision --help
aion usage
aion doctor
aion benchmark
aion welcome

These commands are meant for day-to-day research hygiene: inspect the environment, explore toolkits, track LLM usage, and run lightweight benchmarks.

Migration notes from v0.1.9

1. Upgrade first with a pinned lower bound: aqwel-aion>=0.2.0.
2. Existing 0.1.9 imports (aion.providers, aion.tools, aion.rag, aion.former, maths/algorithms/viz) continue to work.
3. New science/ML modules are additive—import them when you need them; optional extras keep the core install lean.
4. Datasets / data helpers return at the top level in 0.2.0 after the 0.1.9 package trim—prefer aion.datasets / aion.data for loaders and benchmarks. Former text datasets remain under aion.former.datasets.
5. Algorithms — if you depended on transpose/multiply/scaling helpers or A*/PageRank imports, pull 0.2.0 for the fixes listed above.
6. Agents are not part of this wheel. Plan experiments around the shipped library surface, not archived agent code.
7. Docs — on the website, open Aion docs and select v0.2.0 (badge: New). Older versions stay available for historical API checks.

When not to reach for Aion

• Large-scale distributed training or custom CUDA kernels → use your DL framework directly.
• Full planetarium / mission-planning software → universe helpers are intentionally lightweight.
• Production multi-agent coding IDEs → wait for the future agent release; do not build on archived stubs.
• Strict enterprise auth/API gateways → aion api / aion auth are not shipping in 0.2.0.

FAQ

Is v0.2.0 a breaking rewrite of 0.1.9?
No. It is an expansion. Keep your provider/RAG/Former imports; add new modules as needed.

Do I need [full]?
Usually not. Start with core, then add [vision], [serve], or [db] for the workflows you actually run.

Where is the API reference?
aqwelai.xyz/docs/aion — version picker includes 0.1.7–0.2.0.

How do I see environment issues quickly?
aion doctor after install or when optional extras fail to import.

Documentation and next steps

• API reference: Aion docs — switch the version picker to v0.2.0 (New) for the expanded module list.
• PyPI: aqwel-aion
• Home: compare table and live snippets at /#whats-new, /#examples, and /#workflows
• GitHub: Aqwel-AI/aion

Aion is still not a replacement for PyTorch, JAX, or SciPy. It is a research companion: transparent primitives, optional acceleration, and now a wider science and ML toolkit so notebooks stay short and audits stay possible.

If you upgrade, run aion doctor, skim the new modules in the docs, try one physics or vision snippet, and tell us what breaks—or what you want next—on GitHub. Feedback from classrooms and labs shaped 0.1.9; we want the same pressure on 0.2.0.