// the manifesto
no-magic-ai is an umbrella for studying how modern AI actually works. Not a framework. Not a course platform. Not a chatbot. Every repo under this org enforces a single-sentence constraint. Every algorithm points back to a paper. Everything else is off-charter.
// mission
model.fit() isn't an explanation.
Modern AI is taught as a stack of frameworks. transformers.AutoModel. trl.PPOTrainer. peft.LoraConfig.
Contributors learn to call the library, not to derive the algorithm.
no-magic-ai exists to close that loop — by implementing every algorithm from its source paper,
in Python standard library only, one file at a time, so a determined reader can trace every tensor back to its equation.
Our audience is two people: the ML engineer who uses frameworks daily and wants the internals, and the career switcher who read the papers and needs a working implementation they can run on a laptop. Everything we build serves one of these two. When it stops serving them, we delete it.
// the core discipline
no-magic-ai expands through new repos, not feature sprawl. Every repo declares one sentence that governs what belongs
and what doesn't. Repos do not share build systems and do not import each other's code. Cross-repo coupling is limited
to published metadata and links: no-magic's generated docs/catalog.json is read by this website
and checked against paper cards by no-magic-papers CI. The website is the only learner surface that joins them.
// the hard no's
The value of this org is in what it won't do. Every feature we reject keeps the scope tight enough that the code stays readable and the constraints stay honest. These are not deferred — they are off-charter.
No user accounts. No progress tracking. No auth. No server-side state. Static files and GitHub Discussions are the whole platform.
No RAG over the catalog. No AI tutor. A good single-file implementation with the right comments is already the explanation.
No shared base classes. No abstract interfaces. No no_magic.core package. Every script stands alone.
No translations or ports of fast.ai, Karpathy, HuggingFace, or dive-into-llms. We implement from primary sources only.
The code is pedagogical. It is not performant, not distributed, not hardened, and not meant to be imported by your app.
We show how algorithms work, not which beats which. We cite benchmark results from papers; we do not run leaderboards.
// org-wide principles
Every implementation cites its sources and is explicitly mapped to a paper card. Where the code differs from that card, the catalog's adaptation note says so. No content is ported from tutorials, courses, or other educational repos.
A new repo requires a one-sentence constraint that governs it. Violating the constraint is grounds for PR rejection.
Script slugs are no-magic file basenames (e.g. microrope); paper slugs are paper-card names (e.g. rope, gpt-1). One card may own several scripts. Every link is written out; neither slug is derived from the other.
Learner code runs on a laptop CPU. No GPU requirement. No cloud credits. No dataset larger than a few MB; scripts that download one on first run are labelled in no-magic/docs/catalog.json (not yet shown on this site). Maintainer tooling such as apprentice uses its own dependencies and LLM providers.
Code is the primary teaching artifact. Prose explanations live in no-magic-papers/lessons/ and remain optional, never authoritative.
We'd rather write three similar implementations than one abstracted parent class. Duplication is honest; abstraction hides.
Scripts, lessons, and paths that stop serving the two audiences get removed. The catalog is curated, not accreted.
No databases, services or background jobs behind any learner surface. If a learner feature needs stateful infrastructure, it does not belong in this org. apprentice is a maintainer-run CLI with local run records, not a hosted service, and is not activated for autonomous operation.
// sourcing policy
The most important operating rule of this org is what we read while we write. Implementing from the wrong source creates legal exposure and pedagogical noise. These five rules are binding on every contributor and every agent that operates on these repos.
ASSETS.md.no-magic-papers/CONTRIBUTING.md already states a card and lesson pledge; the implementation pledge is not yet written into no-magic/CONTRIBUTING.md, and no signed affirmations are collected. Enforcement is by maintainer review, not by CI.
The dive-into-llms repository (SJTU BCMI) is an excellent curriculum signal but has no LICENSE file.
Its code and prose cannot be redistributed. no-magic-ai has chosen to use its table of contents as a topic menu while
implementing strictly from the primary papers that each chapter cites. No code, prose, or translated content enters this org.
// governance
The project is small enough today that decisions are captured in documents rather than processes. Documents are versioned, readable by agents, and form the standing record. A decision is binding once it lands in the document; disagreement is handled by opening an issue and amending the document.
no-magic-ai-expansion-strategy.md is the top-level doc. Every new repo or charter change references it.
paper-ingestion-process.md describes how a new paper flows through the ecosystem from publication to implementation.
Each repo owns a CONTRIBUTING.md that encodes its single-sentence constraint and review checklist.
Algorithm or math changes, newly interpreted research claims, paper cards, lessons, curriculum and exercise answers need actual human maintainer approval of the current PR head; so do mixed, ambiguous or disputed classifications. AI reviews and agent-posted approvals are not human approval. For the current enhancement phase only, purely technical PRs (tooling, CI, generated metadata, source-state corrections) may be merged by a gated runner after independent review, verification and every required check pass on the current head, and only when both the runner and the independent reviewer classify the current head-versus-base diff as technical (no-magic issue #39). Any change to the head, base or scope invalidates that classification, review and checks.
Open questions, proposals, and curriculum debates live in no-magic Discussions. Resolved items migrate into documents.
// participate
Contributors are welcome. Implementations, lessons, paper summaries, and curriculum paths are all valid contribution surfaces — each gated by its repo's single-sentence constraint. Read the strategy document, pick a candidate, open an issue before writing code.