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

Python 3.11–3.13 is supported.

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 only when basic support checks are met. 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
• 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}
}