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}
}
1 maintainer
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.
Source Distribution
Built Distribution
Filter files by name, interpreter, ABI, and platform.
If you're not sure about the file name format, learn more about wheel file names.
Copy a direct link to the current filters
File details
Details for the file orchid_ranker-1.0.0.tar.gz.
File metadata
- Download URL: orchid_ranker-1.0.0.tar.gz
- Upload date:
- Size: 274.0 kB
- Tags: Source
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
1c5bfdfa198a9904e17c6b6b417723064c108d671818b590e193398714c974b4
|
|
| MD5 |
1321f2473b001bf66fd5d34c8e6abd70
|
|
| BLAKE2b-256 |
68e27e12ed607dba825af5b47c88fd79ce65b05fede392365478b61e35d46576
|
Provenance
The following attestation bundles were made for orchid_ranker-1.0.0.tar.gz:
Publisher:
release.yml on mlgorithm/orchid-ranker
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
orchid_ranker-1.0.0.tar.gz -
Subject digest:
1c5bfdfa198a9904e17c6b6b417723064c108d671818b590e193398714c974b4 - Sigstore transparency entry: 2655052723
- Sigstore integration time:
-
Permalink:
mlgorithm/orchid-ranker@25626bf8cf54a72735a013c96d0943ad0c3c7670 -
Branch / Tag:
refs/tags/v1.0.0 - Owner: https://github.com/mlgorithm
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@25626bf8cf54a72735a013c96d0943ad0c3c7670 -
Trigger Event:
push
-
Statement type:
File details
Details for the file orchid_ranker-1.0.0-py3-none-any.whl.
File metadata
- Download URL: orchid_ranker-1.0.0-py3-none-any.whl
- Upload date:
- Size: 137.4 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? Yes
- Uploaded via:
twine/7.0.0 CPython/3.13.14
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 |
6686f7f53eefa5486b6d31bcc1e372593c9a6610f0a540dac34ff53ee8d26a1e
|
|
| MD5 |
352e08489b201fe7074e0fec1d378852
|
|
| BLAKE2b-256 |
2fd680d69dc8bb9a161aa5bf5a769cc6e255ae036e2900247db21b024156a0f2
|
Provenance
The following attestation bundles were made for orchid_ranker-1.0.0-py3-none-any.whl:
Publisher:
release.yml on mlgorithm/orchid-ranker
-
Statement:
-
Statement type:
https://in-toto.io/Statement/v1 -
Predicate type:
https://docs.pypi.org/attestations/publish/v1 -
Subject name:
orchid_ranker-1.0.0-py3-none-any.whl -
Subject digest:
6686f7f53eefa5486b6d31bcc1e372593c9a6610f0a540dac34ff53ee8d26a1e - Sigstore transparency entry: 2655052730
- Sigstore integration time:
-
Permalink:
mlgorithm/orchid-ranker@25626bf8cf54a72735a013c96d0943ad0c3c7670 -
Branch / Tag:
refs/tags/v1.0.0 - Owner: https://github.com/mlgorithm
-
Access:
public
-
Token Issuer:
https://token.actions.githubusercontent.com -
Runner Environment:
github-hosted -
Publication workflow:
release.yml@25626bf8cf54a72735a013c96d0943ad0c3c7670 -
Trigger Event:
push
-
Statement type:
