Prepare a Runestone CodeTailor version optimized for production (initial attempt)

[xinyinghou]

This PR introduces a Runestone-specific CodeTailor version (codetailor-runestone-ver) based on the latest upstream main branch.

Note:

• This is an initial attempt, expect follow-ups and discussions.
• PR 28 in overview book added questions for dev testing.
• Additional packages are added in pyproject.toml

Runestone-specific version:

• Added CodeTailor modules under book_server_api
  • coach.py
    • In dev mode: coach.py will require a DEV_API key for testing.
    • In production: coach.py will use an instructor-provided API key via fetch_api_token (real service).
    • Can link to instructor-provided Parsons example, this testing blocked in dev mode since question DB isn’t available.
  • personalize_parsons
    • Enable LLM to supply an example solution when no predefined one exists.
    • Remove LLM generation time limit to reduce serving with guardrails
    • Add paired distractors for both two personalization levels
    • Use zero-shot prompting so no extra information is needed
• Added CodeTailor modules under activecode component
  • Only keep two additional specs:
    • :parsonspersonalize: moveable or partial (required)
    • :parsonsexample: id of an existing Parsons problem (optional)
• Added CodeTailor modules under parsons component
  • Added new files for block-level personalization
  • Included an automatically-added spec :scaffolding: to separate scaffolding puzzle code

[bnmnetp]

OK, the good news.

1. It does not appear as though your changes break anything about current activecode or parsons problems

However I can't test any further.

1. Please structure your changes to the overview book like a chapter so that it appears in the table of contents.
2. the book server crashes when I finally figured out how to navigate my wat to the samples. It is missing the openai and I'm guessing javlang modules
3. You should be able to fully test this in a working docker environment. When you have done that please submit your updates.

The documentation for build and running and rebuilding containers is all on https://runestone-monorepo.readthedocs.io/en/latest/

[bnmnetp]

It is good to have these here, but they also need to be added to the pyproject.toml file in the book project.

[xinyinghou]

Thanks, are those the two places to add the new packages? Or is there more places I need to include these two new packages?

[bnmnetp]

Any of the servers that need those libraries need to be updated. I think it is just the book server that you are using to interface to openai.

[bnmnetp]

I also noticed that when it crashed the book server the web page spinner just kept spinning and giving me encouraging messages. You should detect a failure and give an appropriate message to the user.

[xinyinghou]

Yes, I only require them in the book server. I am adding it to the pyproject.toml there

[xinyinghou]

Okay, I will change it to an error message to the user. I am setting it as either resolve when the backend responds, or reject and send an error message if it takes longer than 1 minute.

[xinyinghou]

I also updated the PR in the overview repo to organize my content into a chapter.

[bnmnetp]

Add a comment to keep @barbarer in the loop.

[xinyinghou]

I have

• updated the pyproject.toml under book_server
• added error handling so students see an error message when a failure occurs.

When you have a moment, can you take another look? Thanks!

[bnmnetp]

I tried it again today but no luck.

book-1  | ERROR - 2025-10-21 20:16:00,509 - coach - parsons_scaffolding - 161 - Codetailor: Error fetching API tokens: 'str' object has no attribute 'id'
book-1  | INFO:     172.18.0.9:50718 - "POST /coach/parsons_scaffolding?course=home_overview_fall25 HTTP/1.1" 400 Bad Request

You have a couple of course names hard coded that use the DEV_API key, but I was using a course that would need to use the fetch_api_key call. the course parameter is a string that does not have an id attribute you would need to fetch the course.

[xinyinghou]

If course.id isn’t the correct way for retrieving the course ID needed by fetch_api_key, could you clarify what the correct property or method is? Which API should I refer to for details on how to properly access or identify the course ID in this case? Or can I just put `course_id=course' here since it's already a string?

[bnmnetp]

First of all it is just incorrect python, a string is not a data structure that contains information about a course.

https://docs.runestone.academy has a ton of information, especially on the database api for retrieving what you need. In this case it is simply the fetch_course function, you can see tons of examples of its use.

[xinyinghou]

Sorry, I’m less familiar with the database api code. Thanks for pointing me to the fetch_course function. To clarify, in this case, are you suggesting that I can use course = await fetch_course(course_name) to obtain the CoursesValidator, and then reference course.id as the ID needed for fetch_api_key?

[xinyinghou]

Also, just to clarify, according to the API doc, fetch_api_key returns an Optional[APITokenValidator], which represents the least recently used encrypted API token. Since the token has been encrypted in create_api_token, how should I properly retrieve and use it as plaintext when calling the LLM API (for example, GPT)?
Do I need to manually decrypt it, and if so, what would be the proper way to do that?

[bnmnetp]

It will be decrypted when it is returned.

[xinyinghou]

Got it, so just to confirm, the value returned by fetch_api_key can be treated as a decrypted, plaintext API key that’s ready to use for direct communication with LLMs?

[bnmnetp]

You do not need to confirm, just give it a try!! It is your own instance and you can always back out and change the code!

[xinyinghou]

Thanks! I’ve updated the code to handle course fetch by name to id, and then fetch the instructor-provided API keys using token_record.token from the api_tokens table. Can you please review the changes when you have a chance?

[bnmnetp]

I would like to know if you have tested it? It is super inefficient for you to make code changes and ask me to test them. If you have tested them please let me know that in the updates.

[xinyinghou]

The primary flow has been thoroughly tested using the DEV_API key. However, I haven’t been able to fully test the fetch_api_token part because of persistent issues with the new instructor dashboard setup. I’ve arranged a meeting with Seth to address this. In the meantime, I’d really appreciate your review to check if my understanding and implementation of the instructor-provided key look correct. I’ll finish testing this part once my setup issue is resolved

[bnmnetp]

fetch_course does return None if a course is not found.

[bnmnetp]

See here for instructions on how to interactively try/test the CRUD APIs. https://docs.runestone.academy/en/latest/debugging.html#interactive-testing-with-ipython

Also what kind of persistent issues with the instructor dashboard?

[xinyinghou]

I think the issue is not about the dashboard, but that my current db might be out of date. I am doing a fresh start on the db to see if that fixes things

[bnmnetp]

Ah yes, the build checkdb command will help you run the necessary migrations to get your database synced up with the code.

Any time you see a file added to migrations/versions that means you need to update the database. Its a good idea to just run build checkdb after you do a pull to sync up with main.

[xinyinghou]

thanks, after setting up a new db, I’ve got the instructor dashboard and add_token feature working on my dev server. I’ll test the fetch_api_token part.

[xinyinghou]

Hi Brad, I spent the whole weekend trying to get the changes from Runestone components to show up in the course RST-based books, but I’m still stuck. Here is my flow right now:

1. After getting a fresh db, I added a user.
2. I added that user as an instructor to the course overview -- in this way I got the instructor dashboard.
3. I ran docker compose run rsmanage rsmanage build overview to deploy the overview book. -- I can then see the overview book under Textbooks on the course home page.
4. Since the overview book is still an RST-based book, I switched to this workflow to include CodeTailor code from runestone-components using: poetry install --with=dev, ./build.py --dev under rs/projects/interactives, and runestone build --all deploy under the overview book in the local dev environment

However, my runestone-component changes were never reflected in the book in the course, even after complete rebuilds of both Runestone and the book. The newly deployed version never updates the Textbooks included in the course.
Do you have any suggestions for fixing this or anything I might be missing? What might be your workflow for this case? Thanks!

[bnmnetp]

That is a good and reliable workflow that I still use if I have to do something with RST.

1. Make sure the runestone you are running is coming from the .../rs/.venv/bin folder
2. Look at the generated html and make sure it is using prefix-runtime.bundle.js not something with a hash in the file name.
3. Check the javascript console for any clues
4. Shell in to the book server and make sure that the html that is inside the container matches what you are building outside the container.

[xinyinghou]

Thanks, is there a way to update the runestone components for RST books inside Docker?
Also, right now, only the docker compose run rsmanage rsmanage build book makes the book show up on the course home page, but rsmanage build book (run on my host) doesn’t. Could it be an environment mismatch that’s causing the issue? Do you have any suggestions for fixing it?

[bnmnetp]

Do you get errors with running rsmanage build overview on the host? If your environment is set up properly the container and the host are touching the exact same files that are mounted by the containers.

[bnmnetp]

In fact as the work flow you linked to pointed out you do not even need to use rsmanage you should be using runestone build --all deploy in the overview folder. But just make sure you don't have multiple checkouts of overview and are building in the wrong folder.

[bnmnetp]

Further, make sure that when you run which runestone it is the one in ..../rs/.venv/bin or you will not get the latest.

[xinyinghou]

Yes, when running which runestone, it points to the one in the venv, and there is only one checkout of overview in my host env. When running rsmanage build overview, I got the following: Success! Book deployed

When runestone build --all deploy at the host env, after seeing Done, build successful, I got an error saying "RuntimeError: Cannot configure a Database URL" The DB links I set up in the .env are

DC_DEV_DBURL=postgresql://runestone:runestone@db/runestone_dev
DC_DBURL=postgresql://runestone:runestone@db/runestone

DEV_DBURL = postgresql://runestone:runestone@localhost:2345/runestone_dev
DC_DEV_DBURL = postgresql://runestone:runestone@db/runestone_dev

I’m not sure what caused it, but the workflow (I described before) seems to be working today; the CodeTailor component code now appears in the course book, even though I didn’t change much.

[bnmnetp]

Hmm, the only thing I can think of is that the runestone build command does not know about the .env file in the rs folder. So if you do not have SERVER_CONFIG or the various DBURL environment variables defined in your .bashrc or you have not a command that loads them into your environment then I can see how you would see that runtime error.

[bnmnetp]

I'm glad it is working for you now. In my experience the vast majority of the time problems like you were having boil down to not having your environment variables defined.