Telos

Say the goal. Learn it backward.

Name what you want to achieve — Telos reverse-derives a module-by-module map of the skills you actually need, diagnoses what you already know, and teaches only your gaps.

 
 
 

▶ Try it now — no install, sign in & bring your own key

_{Landing · Run it yourself · How it works · Deploy your own}

The hosted app above runs the full loop in your browser — type any goal and watch Telos build a complete, staged knowledge map. Nothing to install; sign in and bind your own API key once — it's bound to your account (sent per request to the derive endpoint, never stored there), so signing in on any device connects automatically and signing out clears it locally.

goal ─▶ reverse-derive ─▶ a module-organized prerequisite map (30–80 trainable skills)
     ─▶ diagnose what you know (a few smart questions) ─▶ your learning frontier
     ─▶ teach only the gaps (interactive micro-lessons) ─▶ verify ─▶ spaced review ─▶ repeat

Which way is for you?

New here? Just open the hosted app — sign in, bind your key, type a goal, watch it build your map. The rest of this README is for running or hosting it yourself.

Run it yourself (one command)

git clone https://github.com/YunyueLi/telos && cd telos
make          # or: ./start.sh

That's it. make copies core/.env from the template (and tells you where to get a key), installs web deps on first run, then starts the derive proxy and the web app and opens your browser. The app auto-connects to the local proxy — no env vars, no second terminal.

Need a key? Telos works with any OpenAI-compatible provider — e.g. DeepSeek (platform.deepseek.com) or OpenAI. Paste the key into core/.env and refresh. (You can also paste your key + endpoint directly in the app under Settings · Connections — no .env needed.)

What works today

• Reverse-derive any goal into a module-organized prerequisite map — a blueprint pass picks the stages, then each module is expanded in parallel and stitched into one acyclic graph (typically 30–80 trainable skills across 6–9 stages, scaled to the goal's breadth).
• Trainable abilities, not topic lists. Every node is an observable can-do skill with a deliberate-practice drill and a measurable benchmark (novice / proficient / elite) — grounded in deliberate practice and EPA/CEFR/Bloom competency frameworks.
• Adaptive placement diagnosis. Misconception-distractor MCQs + confidence (Certainty-Based Marking) folded into Bayesian Knowledge Tracing, with information-gain item selection over the graph — it asks ~14 smart questions and infers the rest, instead of crude self-report.
• Interactive micro-lessons. Predict → intuition → worked example → self-explain → faded practice → an unscaffolded mastery check — plus real, linkable courses (optionally web-grounded so links never hallucinate).
• Spaced review (FSRS-4.5). What you learn flows into a review queue; due cards reschedule on each grade.
• Six domain classes (declarative · procedural · creative · motor · adversarial · habit) drive different diagnosis & review strategies — so it works for math and a sport and a habit.
• Keep-going system (the Streak tab) — daily goal with a progress ring, a month-view check-in calendar, streak freeze, levels & tiers, and achievements. All bound to real learning signals (mastery & review), never time-on-app, with anti-dark-pattern guards.
• Accounts & cross-device sync (optional, Supabase) — email/password, magic link, or Google; your projects and progress follow you across devices. Without it, everything stays local-first in your browser.
• Nine languages with a self-built i18n layer (zh-CN/TW · en · fr · ja · ko · es · ru · de); dates & relative times localized via Intl.

How it works

Telos is a backward-design engine. You name an outcome; it works backward to the prerequisites, finds where you are on that map (your Zone of Proximal Development), and teaches forward from there — verifying mastery at every step and scheduling spaced review so it sticks.

It splits the paradigm into three independently usable, interoperable data standards:

Configuration & API key

• Hosted app (BYOK): sign in, then bind your own LLM key in Settings · Connections. It's sent with each request to the derive Worker (never stored there) and bound to your account — sign in on any device to connect automatically, sign out to clear it locally.
• Local: put your API key (DeepSeek / OpenAI / any OpenAI-compatible) in core/.env (see above), or paste your key + endpoint in the app under Settings · Connections. Never commit a key — core/.env is git-ignored.
• Optional web search (real, clickable lesson links instead of search pages): set TELOS_SEARCH_PROVIDER=tavily + a key in core/.env. Degrades gracefully if absent.

Full details — local key, Cloudflare Worker, search providers, anti-abuse — in DERIVE.md.

Deploy your own

A static frontend (GitHub Pages) + a Cloudflare Worker that orchestrates the multi-pass derivation. In BYOK mode the Worker uses each user's own key (passed per request, never stored); for a private instance it can hold your key as a fallback. The Worker is the only required backend — everything else degrades gracefully.

1 · Backend — one click, no CLI:

Sign in to Cloudflare (free), then add a secret TELOS_LLM_API_KEY (your DeepSeek/OpenAI key) under the Worker's Settings → Variables and Secrets. You get a https://telos-derive.<sub>.workers.dev URL.

2 · Frontend: fork → GitHub Pages builds automatically. Point it at your Worker via the Actions Variable NEXT_PUBLIC_TELOS_DERIVE_URL = …workers.dev/derive (or just paste the URL in-app, stored per-browser).

Optional — all degrade gracefully if skipped:

Full walkthrough — CLI alternative, secrets, anti-abuse, search providers: DERIVE.md · accounts & sync: SUPABASE.md.

Repo layout

For contributors — the engine, bare

make test                                       # engine test suite (zero deps)
cd core && python3 demo.py                       # end-to-end demo, no web
cd core && python3 derive.py "用 Rust 写高性能 HTTP 服务器"   # reverse-derive in the terminal (needs a key)

Design language

Pure black-and-white on warm paper; a bold serif (Fraunces) + clean sans (Inter) + mono (JetBrains Mono); hand-drawn line icons; a young-teacher mascot in monochrome ink. Full system — tokens, components, gamification visuals, motion — in docs/DESIGN.md.

Research & prior art

Backward design (Understanding by Design), Knowledge Space Theory & ALEKS, the Zone of Proximal Development, Bayesian Knowledge Tracing, Certainty-Based Marking, FSRS spaced repetition, deliberate practice (Ericsson), EPA/CEFR/ACS competency frameworks, and misconception-as-distractor design — full citations in docs/STRATEGY.md.

License

Apache-2.0