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.