A first-class adaptive-learning engine for products where user outcomes matter more than short-term clicks.
Orchid Ranker is built for systems where the user is getting better at something over time: adaptive learning, corporate training, tutoring, onboarding, rehabilitation, fitness progression, and skill-based practice. It combines learner-state tracking, prerequisite-aware candidate selection, live learner-state updates, progression metrics, and safe fallback patterns.
It is not a generic CTR, ads, social-feed, or movie-recommendation model zoo. The core question is: what should this learner work on next so they make measurable progress?
pip install 'orchid-ranker[adaptive]'import pandas as pd
from orchid_ranker import AdaptiveRanker
outcomes = pd.read_csv("learner_outcomes.csv") # learner_id, item_id, correct, ts
catalog = pd.read_csv("exercise_catalog.csv") # item_id, concept_id, difficulty, item_text
ranker = AdaptiveRanker(
kt_backbone="saint+",
policy="auto",
epochs=2,
d_model=32,
).fit_kt(
outcomes.merge(catalog, on="item_id"),
correct_col="correct",
concept_col="concept_id",
item_difficulty_col="difficulty",
)
ranker.fit_semantic_items(catalog, text_col="item_text", metadata_cols=["concept_id"])
ranked = ranker.recommend(learner_id="7", candidate_item_ids=[101, 102, 201, 202], top_k=3)
ranker.observe(learner_id="7", ts=123, item_id=ranked[0].item_id, concept_id=None, correct=1)policy="auto" uses the progression-value policy: the most stable default for
adaptive learning today. Delayed-gain and support-constrained delayed-gain
policies are available as explicit opt-ins when you have the logged support and
reward-model diagnostics to justify them.
Get up and running in under 5 minutes:
- Adaptive learning quickstart --- learner state + prerequisites + live re-ranking
- Use-case cookbook --- compliance, language review, rehab, and safe rollout examples
- Scenario selection quickstart --- choose the right Orchid workflow from product/data signals
- Knowledge tracing quickstart --- SAKT-style predicted correctness
- AKT quickstart --- difficulty-aware monotonic attention tracing
- KT policy quickstart --- rank eligible items by predicted learning value
- Offline policy evaluation quickstart --- IPS/SNIPS/doubly robust rollout checks
- Progression policy quickstart --- reward stretch and learning progress, not just correctness
- pyKT bridge quickstart --- export pyKT sequences and reuse pyKT prediction tables
- Docs quickstart --- install, fit, recommend, evaluate
- Algorithm roadmap --- KT, semantic exercise recommendation, and policy-learning direction
- Fit offline guide --- train on a CSV, save, evaluate
- Usage scenarios --- practical recipes for common Orchid deployments
- Use-case examples --- domain examples that map Orchid APIs to concrete products
Go from adaptive-learning fit to monitored rollout:
- Serve adaptive recommendations --- log decisions, observe outcomes, and rerank from learner state
- Operate safely --- add progression guardrails, Prometheus metrics, Grafana dashboards
Understand what makes Orchid different:
- Benchmark credibility protocol --- one-command JSON + Markdown evidence artifact
- ASSISTments KT benchmark --- adaptive-learning correctness and policy evidence
- KT policy OPE benchmark --- evaluate KT-guided next-item policies before rollout
- Progression policy --- transparent reward design for adaptive sequencing
- pyKT integration --- use Orchid around research KT model zoos
- Learner state. SAINT+/SAINT, AKT/SAKT, DKT/DKVMN-style, PFA/AFM, BKT, and IRT components estimate competence from learner outcomes.
- Catalog structure. Dependency graphs and difficulty metadata keep recommendations in the valid next-step set.
- Semantic cold start. Hashing and dense-adapter semantic encoders retrieve new exercises from text and metadata before interaction support exists.
- Adaptive ranking. Per-user online updates let the next recommendation change after each response.
- Adaptive testing.
IRTAdaptiveSelectorsupports Rasch/2PL/3PL-style placement and mastery-check item selection by information. - Logged policy learning.
AdaptiveRanker.fit_policy(..., algo="cql")trains a conservative CQL-style contextual-bandit policy from candidate sets, rewards, and normalized inverse-propensity update weights. - Personalized exploration.
PersonalizedLinUCBscoresphi(learner, item)features instead of item-only bandit features. - Retention scheduling.
FSRSScheduleradds FSRS-style review urgency for forgetting-aware practice. - Sketch mode. Count-Min, Bloom-filter, reservoir, and exact-vector utilities shrink candidate generation before final reranking.
- Offline policy evaluation. IPS, SNIPS, direct-method, doubly robust, bootstrap, rollout gates, and tabular FQE test adaptive policies before rollout.
- Safe operation. Guardrails and reviewed fallback policies keep adaptive rollouts reviewable.
- Privacy and audit primitives. RBAC (
orchid_ranker.security.AccessControl), HMAC-chained JSONL audit logging (AuditLogger), and hashed event IDs are available as library primitives you wire into your own service. Opt-in DP-SGD is scoped to the experimental two-tower agent path (orchid_ranker.agents.two_tower.TwoTowerRecommender); the flagshipAdaptiveRanker/AdaptiveLearningEngineAPIs do not currently apply differential privacy.
| Family | Orchid APIs | Scenario |
|---|---|---|
| Transformer KT | SAKTTracer, AKTTracer, SAINTTracer, SAINTPlusTracer |
Main next-correctness state models |
| Recurrent / memory KT | DKTTracer, DKVMNTracer |
Compact sequence baselines and ablations |
| Classical EDM | PFATracer, AFMTracer, fit_bkt_em, BayesianKnowledgeTracing |
Small-data, interpretable learner-state baselines |
| Adaptive testing | IRTAdaptiveSelector, IRTItem |
Placement, mastery checks, item-information selection |
| Semantic retrieval | SemanticItemEncoder, DenseSemanticItemEncoder, SemanticExerciseRanker |
Cold-start and metadata-aware exercise retrieval |
| Policy learning | CQLDiscretePolicy, TabularFQE, evaluate_logged_policy |
Logged-policy learning and rollout evidence |
| Exploration | PersonalizedLinUCB |
Safe personalized exploration with explicit feature maps |
| Retention | FSRSScheduler |
Review scheduling and forgetting-risk ranking |
For adaptive learning, start with AdaptiveRanker when you want staged
KT/reward/policy/OPE workflows, or AdaptiveLearningEngine when you only need
fit/rank/observe. They compose
SAINT+/SAINT, AKT/SAKT, DKT/DKVMN-style tracing, progression reward,
difficulty/prerequisite metadata, semantic item retrieval, and live
observe() updates into one fit/rank/observe API. Use lower-level
pieces such as BayesianKnowledgeTracing, DependencyGraph,
ProgressionRecommender, orchid_ranker.kt.SAKTTracer, and
orchid_ranker.kt.SAINTPlusTracer only when you need a custom policy. Use
orchid_ranker.ope to evaluate a new learning policy from logged randomized
traffic before serving it, bootstrap_logged_policy when rollout decisions
need row-resampled confidence intervals, and evaluate_rollout_gate to enforce
minimum support/coverage/clipping thresholds before live learners see a policy. Modern KT and policy-learning
algorithms are tracked in the algorithm roadmap.
Apache 2.0. See LICENSE.
See CONTRIBUTING.md and docs/coding-standards.md. Contributions should keep Orchid focused on adaptive learning, knowledge tracing, progression ranking, safe rollout, and evidence-backed documentation.
@software{orchid_ranker,
title={Orchid Ranker: Adaptive-Learning Engine},
author={Sam Urmian},
year={2024},
url={https://github.com/mlgorithm/orchid-ranker}
}