github.com/code-kern-ai/refinery @v1.15.0

The data scientist's open-source choice to scale, assess and maintain natural language data.

Treat training data like a software artifact.

<a href="https://pypi.org/project/kern-refinery/1.3.0/"><img src="https://img.shields.io/badge/pypi-yellow.svg" alt="pypi"></a>
<a href="https://github.com/code-kern-ai/refinery/blob/master/LICENSE"><img src="https://img.shields.io/badge/License-Apache%202.0-success" alt="Apache 2.0 License"></a>
<a href="https://github.com/code-kern-ai/refinery/discussions"><img src="https://img.shields.io/badge/Discussions-gray.svg?logo=github" alt="GitHub Discussions"></a>
<a href="https://discord.gg/qf4rGCEphW"><img src="https://img.shields.io/badge/Discord-gray.svg?logo=discord" alt="Discord"></a>
<a href="https://twitter.com/MeetKern"><img src="https://img.shields.io/badge/Twitter-white.svg?logo=twitter" alt="Twitter"></a>
<a href="https://www.linkedin.com/company/kern-ai"><img src="https://img.shields.io/badge/LinkedIn-0A66C2.svg?logo=linkedin" alt="LinkedIn"></a>
<a href="https://www.youtube.com/@kern_ai/videos"><img src="https://img.shields.io/badge/YouTube-FF0000.svg?logo=youtube" alt="YouTube"></a>
<a href="https://app.kern.ai/"><img src="https://img.shields.io/badge/Cloud-black.svg?logo=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAACAAAAAeCAYAAABNChwpAAAACXBIWXMAAAsTAAALEwEAmpwYAAAAAXNSR0IArs4c6QAAAARnQU1BAACxjwv8YQUAAALDSURBVHgBvVfBjRUxDLWzf+GCxJeQkLhNJ2wLFIC02wFIcNgG4IBAdMCBBrYD6IS5oYXLcoAL/Bg7iRM7Mx+ElMHSTDxOxn52nMRBKPR4vvwAQA8BELOE+EGQD8QAIYkRgjzMiwyl5WGh8NKXZFD6y1jpP0Jz15ONYzGNRSQtUZYrNBKBPPqn4RDRaSVYEuV/pwYgeEVUYyAtHVW0ZqgoT+5Y4JYUZAMQdSBWr1GVkgGnfegVQZWRjxomScWOHZyw9IKqB8WdPK/FG3lZUOkLdUqsHKrraIKg0RSd8s+uByAIyQSbzV8R4k1KwJIhWKOQEw+InxDq/wlpKJoEOdKeRWcs2WefGoid9x2hm+n5/fTiEQyg59ev37H6817upgBN+7eE+1ciaMmi4e8A+NC7zBlAbJS679S6HOgzFGF7Citcs45jIeCKvt2Tzy8nYb79/M4Zm5dcjJGzPt7wPM0wkGTe7RJPq+D05PYn+bgXbhmEePXq/tMLGEhsOKm3URAwwaLZksISUNlH/hOl4HfhXwBzW/BoKkd2b89vRGuoRmLoABydggjbkEbYroZdP2B0YkilxX5P1z++7k8C6hH98e7pnYsKgOqRm0M0MgJinJuJWOuv2OqEtw8uZ+lPzubDATajXBXh6iFXp2DLbaBURQZOo7BYerTNKqh7LAbnarBns44cvQpaeaaVdMOwy6j6+NP5sy9vUuLIT3w4Mcdtqgdj0iGyxAPkN+XRkQ5JdogHMbNnftIyrSt1GwBnuqwIZs4gKWyzljMYa6EqvC3ZiWIto0OJbL1okJb5fspdDuQ1Wopzbf2rITGHmivbiy0yhfiftvjQ1/VaFVHRa0vwasR/Y7vM1TtFKompFPE26D2U1XtBVmwuIOhimMfRcmHZ61muQn122aC1CADOsEK0YBC05FeACzLXjxbHPu/FapiV/Q23LD/8UGO+6AAAAABJRU5ErkJggg==" alt="Kern AI"></a>
<a href="https://demo.kern.ai/"><img src="https://img.shields.io/badge/Playground-white.svg" alt="Playground"></a>
<a href="https://docs.kern.ai"><img src="https://img.shields.io/badge/Docs-blue.svg" alt="Docs"></a>
<a href="https://www.kern.ai/"><img src="https://img.shields.io/badge/Web-white.svg" alt="Website"></a>

Does one of these scenarios sounds familiar to you?

• You are working on your own side-project in NLP, but you don't have enough labeled data to train a good model.
• You are working in a team and already have some labeled data, but your training data is just stored in a spreadsheet or some TXT-file, and you have no idea how good it actually is.
• You are working in a team about to start a new project with limited resources (annotators, budget, time), and now want to understand how you can best make use of them

If so, you are one of the people we've built refinery for. refinery helps you to build better NLP models in a data-centric approach. Semi-automate your labeling, find low-quality subsets in your training data, and monitor your data in one place.

refinery doesn't get rid of manual labeling, but it makes sure that your valuable time is spent well. Also, the makers of refinery currently work on integrations to other labeling tools, such that you can easily switch between different choices.

DEMO: You can interact with the application in a (mostly read-only) online playground. Check it out here

refinery is a multi-repository project, you can find all integrated services in the architecture below. The app builds on top of 🤗 Hugging Face and spaCy to leverage pre-built language models for your NLP tasks, as well as qdrant for neural search.

Table of contents

• 🧑‍💻 Why refinery?
• Enabling ideas of one-person-armies
• Extending your existing labeling approach
• Put structure into unstructured data
• Pushing collaboration
• Open-source, and treating training data as a software artifact
• Integrations
• Your benefits
• How does Kern AI make money, if refinery is open-source?
• 🤓 Features
• (Semi-)automated labeling workflow for NLP tasks
• Extensive data management and monitoring
• Team workspaces in the managed version
• ☕ Installation
• From pip
• From repository
• Persisting data
• 📘 Documentation and tutorials
• 😵‍💫 Need help?
• 🪢 Community and contact
• 🙌 Contributing
• ❓ FAQ
• Concept questions
• Technical questions
• Service and hosting questions
• 🐍 Python SDK
• 🏠 Architecture
• 🏫 Glossary
• 👩‍💻👨‍💻 Team and contributors
• 🌟 Star History
• 📃 License

🧑‍💻 Why refinery?

There are already many other tools available to build training data. Why did we decide to build yet another one?

Enabling ideas of one-person-armies

We believe that developers can have crazy ideas, and we want to lower the barrier for them to go for that idea. refinery is designed to build labeled training data much faster, so that it takes you very little time to prototype an idea. We've received much love for exactly that, so make sure to give it a try for your next project.

Extending your existing labeling approach

refinery is more than a labeling tool. It has a built-in labeling editor, but its main advantages come with automation and data management. You can integrate any kind of heuristic to label what is possible automatically, and then focus on headache-causing subsets afterwards. Whether you do the labeling in refinery or any other tool (even crowd labeled) doesn't matter!

Put structure into unstructured data

refinery is the tool that brings new perspectives into your data. You're working on multilingual, human-written texts? Via our integration to bricks, you can easily enrich your texts with metadata such as the detected language, sentence complexity and many more. You can use this both to analyze your data, but also to orchestrate your labeling workflow.

Pushing collaboration

While doing so, we aim to improve the collaboration between engineers and subject matter experts (SMEs). In the past, we've seen how our application was being used in meetings to discuss label patterns in form of labeling functions and distant supervisors. We believe that data-centric AI is the best way to leverage collaboration.

Open-source, and treating training data as a software artifact

We hate the idea that there are still use cases in which the training data is just a plain CSV-file. That is okay if you really just quickly want to prototype something at hand with a few records, but any serious software should be maintainable. We believe an open-source solution for training data management is what's needed here. refinery is the tool helping you to document your data. That's how you treat training data as a software artifact.

Integrations

Lastly, refinery supports SDK actions like pulling and pushing data. Data-centric AI redefines labeling to be more than a one-time job by giving it an iterative workflow, so we aim to give you more power every day by providing end-to-end capabilities, growing the large-scale availability of high-quality training data. Use our SDK to program integrations with your existing landscapes.

Your benefits

You can automate tons of repetitive tasks, gain better insights into the data labeling workflow, receive an implicit documentation for your training data, and can ultimately build better models in shorter time.

Our goal is to make training data building feel more like a programmatic and enjoyable task, instead of something tedious and repetitive. refinery is our contribution to this goal. And we're constantly aiming to improve this contribution.

If you like what we're working on, please leave a ⭐!

How does Kern AI make money, if refinery is open-source?

You won't believe how often we get that question - and it is a fair one 🙂 Put short, the open-source version of refinery is currently a single-user version, and you can get access to a multi-user environment with our commercial options. Additionally, we have commercial products on top of refinery, e.g. to use the refinery automations as an actual realtime prediction API.

Generally, we are passionate about open-source and want to contribute as much as possible.

🤓 Features

For a detailed overview of features, please look into our docs.

(Semi-)automated labeling workflow for NLP tasks

• Both manual and programmatic for classifications and span-labeling
• Integration with state-of-the-art libraries and frameworks
• Creation and management of lookup lists/knowledge bases to support during labeling
• Neural search-based retrieval of similar records and outliers
• Sliceable labeling sessions to drill-down on specific subsets
• Multiple labeling tasks possible per project
• Rich library of ready-made automations in our open-source bricks library

Extensive data management and monitoring

• Best-in-class data management capabilities via our databrowser. Filter, sort and search your data e.g. by confidence, heuristic overlap, user, note, etc.
• Integration with 🤗 Hugging Face to automatically create document- and token-level embeddings
• JSON-based data model for up- and downloads
• Overview of project metrics like confidence and label distributions and confusion matrix
• Data accessible and extendable via our Python SDK
• Attribute modifications to extend your attributes (e.g. with sentence complexity metrics) in-place
• Again, you can use bricks to enrich your data with metadata

Team workspaces in the managed version

• Allow multiple users to label your data with role-based access and minimized labeling views
• Integrate crowd labeling workflows
• Automated calculation of inter-annotator agreements

☕ Installation

From pip

pip install kern-refinery

Once the library is installed, go to the directory where you want to store the data and run refinery start. This will automatically git clone this repository first if you haven't done so yet. To stop the server, run refinery stop.

From repository

TL;DR:

$ git clone https://github.com/code-kern-ai/refinery.git
$ cd refinery

If you're on Mac/Linux:

$ ./start

If you're on Windows:

$ start.bat

To stop, type ./stop (Mac/Linux) or stop.bat.

refinery consists of multiple services that need to be run together. To do so, we've set up a setup file, which will automatically pull and connect the respective services for you. The file is part of this repository, so you can just clone it and run ./start (Mac/Linux) or start.bat (Windows) in the repository. After some minutes (now is a good time to grab a coffee ☕), the setup is done and you can access http://localhost:4455 in your browser. To stop the server, run ./stop (Mac/Linux) or ./stop.bat (Windows).

You're ready to start! 🙌 🎉

If you run into any issues during installation, please don't hesitate to reach out to us (see community section below).

Persisting data

By default, we store the data to the directory refinery/postgres-data. If you want to change that path, you need to modify the variable LOCAL_VOLUME of the start script of your operating system. To remove data, simply delete the volume folder. Make sure to delete only if you don't need the data any longer - this is irreversible!

📘 Documentation and tutorials

The best way to start with refinery is our quick start.

You can find extensive guides in our docs and tutorials on our YouTube channel. We've also prepared a repository with sample projects which you can clone.

If you need help writing your first labeling functions, look into our open-source content library bricks.

You can find our changelog here.

😵‍💫 Need help?

No worries, we've got you. If you have questions, reach out to us on Discord, or [open a ticket](https://github.com/code-kern-ai/refinery/discussio