DEV Community: Andrei Parfenov

Building a Grounded LLM Planner for Swim Trainings on Nebius Serverless

Andrei Parfenov — Wed, 24 Jun 2026 19:36:01 +0000

Swimming is one of the few sports where structured training makes a measurable difference. Poor training structure slows progress and builds bad habits that are hard to undo. With the LA2028 Olympics approaching and a fresh wave of interest in competitive swimming, more amateur and age-group swimmers are taking their training seriously. The problem is that training plans have always lived behind a paywall: you either pay for an application or you guess.

Photo courtesy: Deepbluemedia

A good training plan is a decision about how to distribute intensity across weeks, which drills to pair together in a session, and a coaching layer that explains why you're doing what you're doing. These are exactly the kinds of structured reasoning tasks that modern LLMs handle well, but only if they're grounded in real coaching knowledge. This project puts that kind of planning into a serverless API that any swimmer can use, and any coach can shape with their own expertise.

GitHub repo: https://github.com/andreiparfenov/swimming-coach-serverless
End user demo: https://swimming-coach-iota.vercel.app

I was planning to use Vercel or Lambda for this API, but their per-request timeouts don't work for a pipeline that runs for minutes, so I tried a long-running Serverless Endpoint instead.

The system is built on two Nebius Serverless AI components working together: a Serverless Job that builds a curated coaching knowledge base, and a Serverless Endpoint that serves the actual planning API. Now, let’s walk through how each piece was actually built and deployed, commands included, so you can follow along or adapt it for your own project.

Step 1: Build the planning API locally first

Before touching any Nebius Serverless infrastructure, make sure the application is working entirely on your own machine. The app itself is a small FastAPI service with three chained agent calls:

async def generate_plan(profile: SwimmerProfile) -> TrainingPlan:
    macro = await run_periodization_agent(profile)
    weeks_raw = await run_session_agent(profile, macro)
    weeks_enriched = await run_coaching_agent(profile, weeks_raw)
    ...

The periodization agent takes the swimmer's profile and decides the macro structure of the plan: week themes, intensity, and a volume curve. The session generator runs once per week and fills in the warmup, main set, and cooldown in pool lengths. The coaching notes agent batches every session into a single call and writes a short note for each one. Splitting the work this way, instead of asking a single prompt to do everything, keeps each call's output schema small and makes it far easier to work out which step has gone wrong when something does go wrong.

To run it locally:

cp env.example .env
# fill in NEBIUS_API_KEY in .env

pip install -r requirements.txt
uvicorn app.main:app --reload

If you don't have a Token Factory API key, go to https://tokenfactory.nebius.com, sign in, and create a key under API keys. It's only shown once, so copy it straight away. NEBIUS_API_KEY is used to authenticate every agent call.

Then test it:

curl -X POST http://localhost:8000/generate-plan \
  -H "Content-Type: application/json" \
  -d '{
    "level": "intermediate",
    "goal": "endurance",
    "sessions_per_week": 3,
    "session_duration_minutes": 60,
    "pool_length": 25,
    "weeks": 4
  }'

Step 2: Containerise and deploy the Endpoint

Once it works locally, the next step is packaging it for Nebius.

The Nebius CLI needs to be installed and authenticated (nebius auth login), and Docker needs to be logged in to whichever registry you're pushing to (docker login). Both are one-time setup steps.

Let’s package:

docker buildx build --platform linux/amd64 -t docker.io/<your-username>/swimcoach-api:latest --push .

Nebius Endpoints need a subnet to attach to, which can be picked up automatically if you only have one:

SUBNET_ID=$(nebius vpc subnet list --format jsonpath='{.items[0].metadata.id}')

Then create the Endpoint itself:

nebius ai endpoint create \
  --name swimcoach-api \
  --image docker.io/<your-username>/swimcoach-api:latest \
  --platform cpu-e2 \
  --preset 2vcpu-8gb \
  --public \
  --container-port 8000 \
  --subnet-id "$SUBNET_ID" \
  --env "NEBIUS_API_KEY=$NEBIUS_API_KEY" \
  --env "MODEL_ID=meta-llama/Llama-3.3-70B-Instruct"

A CPU preset is enough here. The Endpoint doesn't run any model locally and only orchestrates calls out to Token Factory, so there's no benefit in paying for a GPU. cpu-e2 / 2vcpu-8gb is simply what this workload needs. You can run nebius ai endpoint create --help to see the full range of platforms and presets if you want to size it differently.

After two to three minutes, the endpoint moves to Running and prints a public address:

nebius ai endpoint get-by-name --name swimcoach-api --format json

curl http://<public-ip>:8000/health
# {"status": "ok"}

Step 3: Build the knowledge base as a Serverless Job

A language model will happily produce a plausible-sounding training volume instead of a correct one. So, before planning agents are asked to produce anything, they need a source of real coaching knowledge to ground their decisions.

This is where we'll use the second Nebius primitive. A Serverless Job runs once, offline, and is well-suited to a task like this because there's no need to keep it running afterward. Once it's done, the compute is released automatically. The job loads twelve hand-written coaching profiles (one per combination of swimmer level and training goal) from job/seed_data/training_principles.json (already included in the repo) and for each one makes a single call to Token Factory to compress the structured data into a short coaching summary suitable for prompt injection. The result is written to knowledge_base.json and uploaded to Nebius Object Storage.

The seed data is the part that actually determines whether the grounding means anything. training_principles.json was drafted to reflect widely published, publicly available swim coaching methodology documented in places like USMS's free training resources and British Swimming/Swim England's published coach education materials.

The Job needs its own credentials for Object Storage. A static access key is tied to a service account, so create one of each first:

PARENT_ID=<your-project-id> # find it via `nebius profile list`, then check the
                            # parent-id field for that profile in ~/.nebius/config.yaml

nebius iam service-account create --name swimcoach-storage-sa --parent-id "$PARENT_ID"
# → note the service account id from the output

nebius iam v2 access-key create --account-service-account-id "$SA_ID" --parent-id "$PARENT_ID"
# → aws_access_key_id is S3_ACCESS_KEY, secret is S3_SECRET_KEY

With those in hand:

cd job
export NEBIUS_API_KEY=<your-tokenfactory-key>
export S3_ACCESS_KEY=<from-the-access-key-output-above>
export S3_SECRET_KEY=<from-the-access-key-output-above>

docker buildx build --platform linux/amd64 -f Dockerfile.job -t docker.io/<your-username>/swimcoach-job:latest --push .

nebius ai job create \
  --name swimcoach-data-processor \
  --image docker.io/<your-username>/swimcoach-job:latest \
  --platform cpu-d3 \
  --preset 4vcpu-16gb \
  --env "NEBIUS_API_KEY=$NEBIUS_API_KEY" \
  --env "S3_ACCESS_KEY=$S3_ACCESS_KEY" \
  --env "S3_SECRET_KEY=$S3_SECRET_KEY" \
  --env "S3_BUCKET=swim-program"

Check on it with:

nebius ai job logs <job-id> --follow

A successful run enriches all twelve profiles and ends with Uploaded to s3://swim-program/knowledge_base.json.

Step 4: The Object Storage permission wall

Nebius Object Storage doesn't grant a service account access to a bucket simply because that service account belongs to the same project. Access has to be explicitly granted through a bucket policy rule, and that rule can only be scoped to a group, not directly to an individual service account. So the fix is a short sequence:

# 1. Work out which service account the storage key belongs to
nebius iam v2 access-key list --parent-id "$PARENT_ID" --format json
# match on status.aws_access_key_id, read spec.account.service_account.id

# 2. Put that service account into a group
nebius iam group create --name swim-program-writers --parent-id "$PARENT_ID"
nebius iam group-membership create --parent-id "$GROUP_ID" --member-id "$SERVICE_ACCOUNT_ID"

# 3. Grant the group write access on the bucket
nebius storage bucket update --id "$BUCKET_ID" \
  --bucket-policy-rules '[{"group_id": "'"$GROUP_ID"'", "paths": ["*"], "roles": ["storage.editor"]}]'

I folded the whole sequence into the deployment script deploy_job.sh, which is written to check first and only create what's missing.

Step 5: Wiring the knowledge base into the prompts

The Endpoint doesn't read the knowledge base from Object Storage on every request. That would add an unnecessary network call to every/generate-plan request for data that rarely changes. Instead, it fetches knowledge_base.json once per container lifetime, on first use after the container starts, and keeps it in memory for as long as that process runs:

def _load() -> dict:
    global _knowledge_base
    if _knowledge_base is None:
        _knowledge_base = _fetch_from_object_storage()
        if _knowledge_base is None:
            with open(_LOCAL_KB_PATH) as f:
                _knowledge_base = json.load(f)
    return _knowledge_base

If Object Storage credentials aren't configured, or the fetch fails for any reason, it falls back to a bundled copy committed in the repo, so local development with no S3 credentials at all still works, and a brief Object Storage outage doesn't take the Endpoint down with it.

This means refreshing the knowledge base after the Job runs doesn't need a rebuild or a new deployment. It needs the container to restart so it re-fetches on the next startup. Nebius Endpoints support exactly that with stop and start, separate from delete/create:

nebius ai endpoint stop <endpoint-id>
nebius ai endpoint start <endpoint-id>

Results

The Job is CPU-only and finishes in one to three minutes. The Endpoint, also CPU-only, runs five or six sequential calls to Token Factory per /generate-plan request: one for periodization, one per week, and one batch call for coaching notes, so the total latency scales with the number of requested weeks. Measured end-to-end, a four-week plan takes roughly three minutes; a two-week plan takes about half that. That's a deliberate trade-off: each step's output is small and easy to validate on its own, at the cost of a request that takes minutes rather than seconds.

A small static frontend with plain HTML, CSS, and JavaScript turns the JSON response into a plan that reads the way a swimmer would actually read a workout on a whiteboard: warmup, main set, and cooldown, each set written out as reps, distance, and rest.

Generating a four-week plan makes seven Token Factory calls totalling roughly 9,000 tokens, at Llama 3.3 70B's rate of $0.13/1M input and $0.40/1M output. It’s about a quarter of a cent per plan. The Endpoint container is the main cost driver. It runs continuously regardless of traffic. Checked against Nebius's own cost calculator (nebius billing v1alpha1 calculator estimate), the smallest non-GPU preset (cpu-e2 / 2vcpu-8gb) comes out to roughly $1.19/day in compute.

#NebiusServerlessChallenge

Search and Replace: Getting Started with the Notion API SDK for JavaScript

Andrei Parfenov — Thu, 29 Dec 2022 09:31:56 +0000

Notion is a powerful tool for creating and managing a variety of digital content, such as notes, articles, and databases. However, one feature that many users have requested for a long time is the ability to search and replace text within Notion documents and pages.

I have a lot of documents in my Notion databases and often need to search through all of the pages and replace specific words and phrases.

For example, I have a table with instructions on how to work with remote repositories, and I want to replace all instances of "GitHub" with "GitLab" in every document:

In this post, I'll show you how to create a simple workaround to search for text and replace it in multiple documents inside a Notion database. All you need is Node.js installed on your machine.

Link to a GitHub repo with the full code: https://github.com/andreiparfenov/search-and-replace-notion-api

Notion API Reference: https://developers.notion.com/reference/intro

This is a very simple workaround where I mostly tried to experiment with the Notion API. Please note that I was only able to implement a solution for Notion text blocks or paragraphs. My script will not work for headings, code snippets, etc. because different block types have different object properties in the Notion API. The code is also far from perfect, so feel free to leave your suggestions for improvement. Also, share about your experience working with the Notion API.

Here's a step-by-step instruction.

Set up Notion

Assuming that you have an account on Notion, go to the "My integrations" page. Click the "New integration" button. Create an internal integration with the ability to read, update, and insert content:

Go to the database you want to work with, press "Settings" (three dots), and then click "Add connections". Choose the newly created integration.

Set up the Node.js app

Notion has a JavaScript client for the API. We'll create a folder for the new Node.js project and initialize package.json inside:

mkdir notion-search-and-replace
npm init

Now that we have the package.json file, let's install a package with the Notion SDK:

npm install @notionhq/client

Create a Node.js file (I created app.js) in the project folder and initialize the Notion client:

const { Client } = require("@notionhq/client");

const notion = new Client({
  auth: process.env.NOTION_TOKEN,
});

NOTION_TOKEN is your internal integration token from Notion. If you share your code with others, make sure that it's kept in .env as well.

Next, specify the value that the script will search for and what it should be replaced with. I want to replace all occurrences of "GitHub" with "GitLab" in my text:

const searchValue = "GitHub";
const newValue = "GitLab";

Create an entry point function:

(async () => {
  const db = await notion.databases.query({
    database_id: process.env.NOTION_API_DATABASE,
  });

  for (const page of db.results) {
    // we'll access the page's blocks here and update them
  }
})();

In this function, we access the database by its ID and create a loop to iterate over the pages (the results property) inside the database.

When we access each page from the database, we'll need to access the page's blocks. Let's do it in a separate function:

async function retrieveBlocks(pageId) {
  const page = await notion.blocks.children.list({
    block_id: pageId,
  });

  return page.results;
}

On Notion, a page is also a block. That's why in the code above we access the children property of blocks.

We'll need to go one more level down and access the text inside each block. Let's add the following function:

async function findAndReplace(blocks) {
  for (const block of blocks) {
    if (!block.paragraph) continue;
    const textItems = block.paragraph.rich_text;
    const newTextItems = textItems.map((item) => {
      const selectedText = item.text.content;
      const newText = selectedText.includes(searchValue)
        ? selectedText.replaceAll(searchValue, newValue)
        : selectedText;
      item.text.content = newText;
      return item;
    });
    // we'll update the corresponding block here
  }
}

In this function, we use the paragraph.rich_text property, which is an array of objects. Yes, the text content is actually an array where elements are split by their formatting style. It may sound complicated, but here's an example:

I love GitHub.

If this is a Notion paragraph, it will have four elements in the rich_text array:

"I" - non-formatted
"love" - bold
"GitHub" - code
"." - non-formatted

Read more about rich-text in the Notion API's docs.

Then we use map() to replace every needed instance.

Finally, let's update the entire block and insert the new text items:

async function updateBlock(block, newTextItems) {
  const selectedBlock = await notion.blocks.update({
    block_id: block.id,
    paragraph: {
      rich_text: newTextItems,
    },
  });
}

Update the findAndReplace() function by calling updateBlock() at the very end of the for...of loop:

async function findAndReplace(blocks) {
  for (const block of blocks) {
    // all the previous code
    await updateBlock(block, newTextItems);
  }
}

Also, update the entry point function:

(async () => {
  const db = await notion.databases.query({
    database_id: process.env.NOTION_API_DATABASE,
  });

  for (const page of db.results) {
    // call functions retrieveBlocks and findAndReplace here
    const blocks = await retrieveBlocks(page.id);
    findAndReplace(blocks);
  }
})();

Run the code with the following command:

node app.js

The script will replace all instances of "GitHub" in all the documents inside the database:

I hope you find this useful. Share how you use the Notion API to automate your work. 🤖