[ENG-1182] Rename api.create_prompt() to get_or_create() and update doc/cookbook

[desaxce]

https://www.loom.com/share/361ece4a20a2495d966521a7adcde7ed

Edit: Just noticed that the checksum for exact same (settings, template_messages) is different.
The issue is with our seed data not computing the checksum, so it looks like the current prompt version we have in DB differs from the newer passed as argument.

I adapted the APIs around prompts:

• deprecated create_prompt for get_or_create_prompt
• added id argument on get_prompt

To test with https://github.com/Chainlit/chainlit-cloud/pull/437.

• Need to change checkSum for PromptVersion with ID 67907431-95dc-56cd-9cb2-ed657122e59f to 7627fac5400b71fabfa1798ea01cbe179737abb11101131fe24cb45236d19ac8 on staging PG (DigitalOcean)
• Add video
• Test get_prompt with id

I removed the exclude = "examples/" from mypy.ini because I think the syntax is incorrect: the examples directory is excluded from mypy checks only if it is without double quotes. Anyway, I don't think we should exclude examples from linting.

Choosing the right deprecated annotation

I recommend we don't rely on private packages like https://pypi.org/project/Deprecated/.
PEP 702 standardizes deprecated as part of the warnings module.
Python 3.13 implements PEP702 and older Python versions can just import it from typing_extensions.
It just lacks some version argument to tell which last version will be supported.

If users installed the Python extension on VS Code, it will automatically install Pylance which will strike through deprecated occurrences throughout the code. In the auto-completion suggestions though, deprecated methods do not show as stricken through (no indication that users shouldn't use it):

On Cursor.sh (latest AppImage for Linux - version 0.32.2), no luck getting the strike through: the extensions fetched from Cursor seem stale (Pylance is v2023.10.40) while VS Code offers v2024.4.1. I cannot say for sure that's the culprit, maybe something else in my setup is incorrect.

---

This change is 

[linear]

ENG-1182 Rename api.create_prompt() to get_or_create() and update doc/cookbook

client.create_prompt()

CRUD with versioning.

U => version bump.

• create_prompt(name, prompt) -> a first call creates a v0
• create_prompt(name, prompt) -> subsequent calls only return v0 (no creation, currently implicit for user)
  • rename to get_or_create / upsert
• create_prompt(name, new_prompt) -> v1
  • create_or_increment / update_prompt
• get_prompt(name) -> champion
• get_prompt(id) ->
• get_prompt(name, version)

Implement TS client too.

Check how deprecated appears in the automatically generated documentation.

For now we deprecate the create_prompt.

We expose create_prompt_lineage at the moment.

Adapt all pieces of docs (in code, in literal-docs, in cookbooks)

[desaxce]

@laura-ham I found this way to have the async versions of the APIs point to the sync ones. I haven't updated all the APIs in case the docs differ.

[willydouhard]

Reviewed 6 of 7 files at r2, 1 of 1 files at r3, all commit messages.
Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @laura-ham)

---

literalai/api/__init__.py line 2370 at r2 (raw file):

Previously, desaxce (Hugues de Saxcé) wrote…

@laura-ham I found this way to have the async versions of the APIs point to the sync ones. I haven't updated all the APIs in case the docs differ.

Nice!

[willydouhard]

Reviewable status: all files reviewed, 1 unresolved discussion (waiting on @laura-ham)