Orchid Ranker

Orchid Ranker is an adaptive-practice engine for learning products.

It chooses the next eligible exercise, observes the learner's result, and adapts the next recommendation. It is designed for assessed practice, technical-skills training, test preparation, and professional certification— not generic feed or product recommendation.

Your platform owns the curriculum, content, safety rules, and learner experience. Orchid owns the adaptive decision loop and the evidence needed to test whether it improves retained mastery.

Install

pip install orchid-ranker

The base install runs the empirical learner without PyTorch. To evaluate neural knowledge tracing on a sufficiently supported course, install orchid-ranker[kt] instead. With the default fallback enabled, a base install uses the empirical learner when PyTorch is unavailable and reports that choice in learning_readiness().

Python 3.11–3.13 is supported. The main branch may contain unreleased APIs. To use the code and guides from this checkout, run python -m pip install -e .; the command above installs the latest published release.

Use it

You need four columns: learner, exercise, outcome, and timestamp. In the API these stay domain-neutral as user_id, item_id, outcome, and timestamp.

import pandas as pd
from orchid_ranker import AdaptiveRanker

history = pd.DataFrame({
    "user_id":   ["learner-a", "learner-a", "learner-a", "learner-b", "learner-b", "learner-b"],
    "item_id":   [101, 102, 201, 101, 102, 201],
    "outcome":   [1,   1,   0,   1,   0,   0],  # correct / not yet correct
    "timestamp": [1,   2,   3,   1,   2,   3],
})

ranker = AdaptiveRanker().fit(history)

# Inspect whether this pilot has enough support for knowledge tracing.
print(ranker.learning_readiness())

ranked = ranker.recommend(
    user_id="a",
    candidate_item_ids=[101, 102, 201],
    top_k=2,
)

ranker.observe(
    user_id="a",
    item_id=ranked[0].item_id,
    outcome=1,
    timestamp=4,
)

This is the complete loop. Small pilots automatically use a transparent empirical learner; Orchid uses knowledge tracing when basic support checks are met and PyTorch is installed. outcome is binary: 1 for a completed/correct practice result and 0 otherwise. Do not use clicks as a learning outcome.

Your application supplies only pedagogically eligible items. It should enforce availability, prerequisites, assessment holdouts, accommodations, and any other hard curriculum rules; Orchid only orders that set.

Learn more

• Quickstart
• How Orchid works
• Adaptive-practice data readiness
• API
• Production serving and decision logging
• Run a learning-efficacy pilot
• Pilot integration contract
• End-to-end reference-pilot workflow
• One-course sample study
• 1.x API support policy
• Validate an adaptive rollout

Development

python -m pip install -e '.[dev]'
./scripts/run_full_tests.sh

See CONTRIBUTING.md, docs/coding-standards.md, and RELEASING.md.

Community and support

Use SUPPORT.md for usage and contribution guidance, CODE_OF_CONDUCT.md for participation expectations, and SECURITY.md for private vulnerability reporting. The canonical software-citation metadata is in CITATION.cff.

License

Apache 2.0. See LICENSE.

Citation

@software{orchid_ranker,
  title={Orchid Ranker: Outcome-Driven Adaptive Recommendation},
  author={Sam Urmian},
  version={1.0.0},
  year={2026},
  url={https://github.com/mlgorithm/orchid-ranker}
}