LibreCO*IR is a free and open source implementation of various fair ranking algorithms, targetting the sphere of open web search.
LibreCO*IR is implemented primarily in C/C++, with evaluation code written in R and SWI-Prolog.
C/C++ was chosen as the implementation language for reasons of ubiquity, higher performance in low-spec environments, and compatibility within software engineering packaging culture. x86-compiled programs can be easily integrated into the package repositories of most server-side operating systems. Higher-level dependencies and languages can complicate this process.
A few other software packages with similar design goals, i.e. using a low-level paradigm: SQLite, Redis, Git and DuckDB.
For this reason, a number of fairness algorithms are included in LibreCO*IR, some focusing on group fairness, others focusing on individual fairness (group labels are not available to all organisations). Additionally, LibreCO*IR introduces a novel greedy individual fairness method, aimed at lower-end hardware, for scenarios where ILP and parallelism might fall beyond budget.
git clone https://github.com/seanhly/coir.git librecoir
(cd librecoir && make install)
# Cleanup
rm -r librecoir
coir‑daemon) and another for the user's client,
i.e. a command-line interface (coir). The server command
(coir‑daemon) can be run without any additional
arguments, whereas the client command (coir) requires more instruction
(§ CLI Usage).
A server/client model
was chosen for performance reasons. Some fairness techniques, especially
amortized fairness,
involve the real-time logging of exposure and click data. This information
then impacts the results received upon subsequent instantiations of the given
query. In a server/client model, even when the client process
(coir) ends, the server continues to hold the program state in
memory. Communication
between the client and server (IPC) is achieved via
named pipes. Future work
might look towards shared memory
as an alternative IPC approach, or network-based IPC in the case of distributed
systems. For now, named pipes offer ease of development and security benefits.
Ctrl+C or
killall coir‑daemon. After this, the user can
begin requesting re-rankings for given queries. Queries are first specified in a file format,
though subsequent requests can use the query ID as a standalone additional argument.
In the first line of code executed on the client-side (right), a re-ranking of
documents for a query file are requested, with a quality threshold of 0.99 and using individual amortized fairness (IAF) as the
re-ranking method. The default method used here is a greedy version of IAF,
i.e. no integer linear programming or matrix de-composition.
coir-daemon # Starts the server
# Rerank the query's results
# … using individual amortized fairness
# and quality threshold of 0.99
coir rerank iaf 0.99 < query
# Output:
# d0
# d1
# d2
# d3
# d4
# d5
# Rerank the query results
coir rerank iaf 0.99 < query
# d3
# d1
# d2
# d0
# d5
# d4
When the second reranking was requested, note that different results
were returned. This illustrates the fairness intervention at work:
items are ranked not just according to quality but also according to
which items have been under-represented thus far.
# Re-rank again using the FairCo method
coir rerank fairco 0.99 < query
# Output:
# d1
# d0
# d2
# d4
# d3
# d5
# Rerank a fourth time, using fairco
coir rerank fairco 0.99 < query
# d3
# d1
# d2
# d0
# d5
# d4