# NTO AI Final Baseline

*English translation by SOTA – AI Community of the Russian original. Organisers who would like this translation removed can email sota.ai.community@gmail.com.*

This repository is the baseline for the final case of NTO AI, "Lost Items". The task in a nutshell: from incomplete logs and metadata, restore for each user in `targets.csv` the top 20 most likely lost positive interactions with books.

The baseline already contains a reproducible pipeline, local validation, data contracts and the submission format. At the same time, it has been deliberately kept fairly simple: our aim is not to give you an "almost finished solution", but to give you a convenient framework for fast experiments and for integrating new ideas.

You can run the project with a single command right now:

```bash
uv run python -m src.platform.cli.entrypoint run --config configs/experiments/baseline.yaml
```

## What to read first

Yes, we are asking you not to rush into development in the first seconds, but to read what you are given. You will spend 20 minutes of your time, but save 4 hours of debugging. 

For clarifications, you can turn to the mentors, the case holder or GPT.

| Document | Why read it |
|---|---|
| [`docs/baseline/SETUP.md`](docs/baseline/SETUP.md) | How to run the pipeline and where to find the artefacts |
| [`docs/baseline/ONBOARDING.md`](docs/baseline/ONBOARDING.md) | Overall map of the baseline |
| [`src/competition/README.md`](src/competition/README.md) | Where changes are most often worth making |
| [`src/platform/README.md`](src/platform/README.md) | How the infrastructure layer is organised |
| [`docs/task/task_description.md`](docs/task/task_description.md) | Task statement and metric |
| [`docs/task/data_description.md`](docs/task/data_description.md) | Data schema |
| [`notebooks/EDA.ipynb`](notebooks/EDA.ipynb) | A very simple overview of the `Dataset` object and the available tables |

## What is already implemented in the baseline

The current baseline follows a stage-based pipeline:

```text
prepare_data -> build_features -> generate_candidates -> rank_and_select -> make_submission
```

In terms of what it does:

- builds a `Dataset` from the input CSV files
- builds simple features
- generates candidates from several sources
- ranks the candidates and produces the final `submission.csv`
- caches intermediate artefacts so that identical stages are not recomputed

Architecturally, the repository is divided into two zones:

- [`src/competition/`](src/competition/) — the solution zone, which is what you need to extend
- [`src/platform/`](src/platform/) — the run infrastructure, which usually does not need to be changed

## The baseline is deliberately naive in DS terms, but rich in engineering

We have kept several things simple:

- the generators and the ranker in the baseline are heuristic and minimalistic
- the common pipeline contains no model training
- feature engineering in the baseline is shown only as a starting point, not as a strong production-grade feature set

We expect you to add, replace and improve:

- new features
- new candidate generators
- stronger rankers
- externally trained models and their integration into the common pipeline

## How we recommend working with it

The baseline is built so that it is convenient for a team of two participants to use.

First, different models and ideas can be developed separately and then combined inside the common baseline. This is convenient both for parallel work and for the careful integration of new features, generators and rankers.

Second, the baseline has no built-in training stage. Any training of your models can be moved into separate notebooks or scripts, and the main pipeline then simply loads ready-made weights, coefficients, feature tables or other artefacts for the generator and the ranker. If you wish, there can be several rankers and generators.

Third, as the organisers, we suggest treating this baseline as a research platform:

- if you have useful features, candidates or rankers left over from the previous stages, it makes sense to port and adapt them here
- we encourage the use of AI tools, provided that they are free and do not break the NTO rules: you can generate drafts of functions, generators, rankers and feature files, and then quickly integrate them into `competition`

Fourth, the more complex pipeline with caching exists not for the sake of "engineering beauty" but for the speed of experiments. If you have already run a stage and its inputs have not changed, the baseline will try not to recompute it, or to make the repeated run as fast as possible.

## Our main principle

First and foremost, we see you as researchers and experimenters. We have deliberately pushed the engineering and pure-Python part into the background. Your main priority here is to come up with and test a strategy for improving the metric, quickly integrating new ideas into the ready-made baseline framework.