LLM Tutorial

This walks through using OAK through an LLM wrapper.

See also How-to guide.

Note for this to work, you must either install OAK with llm extras, or do a separate install of pipx install llm.

You will also need the API keys for an LLM service, or a proxy to a local model.

Annotate Command

Note the first time you run this it may be slow, as it needs to perform an initial embedding.

Here we use the standard OAK annotate command, but instead of the usual adapter (e.g. sqlite:obo:cl), we pass in a wrapped adapter, using the gpt4-o model.

We strongly recommend passing in categories, as this helps the model ground the kinds of terms you are interested in.

!runoak --stacktrace -i llm:{gpt-4o}:sqlite:obo:cl annotate "sequencing was performed on splenic and thymic macrophages" --category CellType

object_id: CL:0000871
object_label: splenic macrophage
object_categories:
- CellType
subject_label: splenic macrophages

---
object_id: CL:0000866
object_label: thymic macrophage
object_categories:
- CellType
subject_label: thymic macrophages
start: 40
end: 58

Currently the specific span coordinates are only returns for concepts that can be clearly mapped back to the text.

You can also use the standard --whole-text (-W) option to match the entire text span, rather than to annotate segments:

!runoak --stacktrace -i llm:{gpt-4o}:sqlite:obo:cl annotate -W "macrophage found in the thymus" --category CellType

object_id: CL:0000866
object_label: thymic macrophage
subject_label: macrophage found in the thymus

Suggesting Definitions

!runoak -i llm:sqlite:obo:uberon generate-definitions \
     finger toe \
     --style-hints "write definitions in formal genus-differentia form"

add definition 'A manual digit is a type of anatomical structure characterized as one of the distal appendages found on the human hand, distinct from those structures on other limbs, and is primarily comprised of phalanges, a metacarpal bone, and associated soft tissue.' to UBERON:0002389
add definition 'A pedal digit is a type of anatomical structure that is a subdivision of the limb and is specifically located at the distal end of the pes, commonly known as the foot, in vertebrates.' to UBERON:0001466