Natural Language Based APIs#

Being able to understand the content of text can help in tasks other than information extraction.

Here, we’ll see how extracting information from text can help with powering a natural language based assistant that has different skills.

from kor import create_extraction_chain, Object, Text, Number
from langchain_openai import ChatOpenAI

llm = ChatOpenAI(
    model_name="gpt-4o",
    temperature=0,
    max_tokens=2000,
)

Control Music#

Here’s a hypotehtical API for controlling music.

schema = Object(
    id="player",
    description=(
        "User is controlling a music player to select songs, pause or start them or play"
        " music by a particular artist."
    ),
    attributes=[
        Text(
            id="song",
            description="User wants to play this song",
            examples=[],
            many=True,
        ),
        Text(
            id="album",
            description="User wants to play this album",
            examples=[],
            many=True,
        ),
        Text(
            id="artist",
            description="Music by the given artist",
            examples=[("Songs by paul simon", "paul simon")],
            many=True,
        ),
        Text(
            id="action",
            description="Action to take one of: `play`, `stop`, `next`, `previous`.",
            examples=[
                ("Please stop the music", "stop"),
                ("play something", "play"),
                ("play a song", "play"),
                ("next song", "next"),
            ],
        ),
    ],
    many=False,
)

ATTENTION Use the JSON encoder here rather than the default CSV encoder as it supports nested lists

chain = create_extraction_chain(llm, schema, encoder_or_encoder_class="json")

Music Player#

chain.invoke("stop playing the music now")['data']

{'player': {'action': 'stop'}}

chain.invoke("i want to hear a song")["data"]

{'player': {'action': 'play'}}

chain.invoke("can you play the lion king soundtrack")["data"]

{'player': {'album': ['the lion king soundtrack'], 'action': 'play'}}

chain.invoke("play songs by paul simon and led zeppelin and the doors")

{'data': {'player': {'artist': ['paul simon', 'led zeppelin', 'the doors'],
   'action': 'play'}},
 'raw': '<json>{"player": {"artist": ["paul simon", "led zeppelin", "the doors"], "action": "play"}}</json>',
 'errors': [],
 'validated_data': {}}

chain.invoke("could you play the previous song again?")["data"]

{'player': {'action': 'previous'}}

Ticket ordering#

Here’s an imaginary API for searching and buying tickets

schema = Object(
    id="action",
    description="User is looking for sports tickets",
    attributes=[
        Text(
            id="sport",
            description="which sports do you want to buy tickets for?",
            examples=[
                (
                    "I want to buy tickets to basketball and football games",
                    ["basketball", "footbal"],
                )
            ],
        ),
        Text(
            id="location",
            description="where would you like to watch the game?",
            examples=[
                ("in boston", "boston"),
                ("in france or italy", ["france", "italy"]),
            ],
        ),
        Object(
            id="price_range",
            description="how much do you want to spend?",
            attributes=[],
            examples=[
                ("no more than $100", {"price_max": "100", "currency": "$"}),
                (
                    "between 50 and 100 dollars",
                    {"price_max": "100", "price_min": "50", "currency": "$"},
                ),
            ],
        ),
    ],
)

chain = create_extraction_chain(llm, schema, encoder_or_encoder_class="json")

chain.invoke("I want to buy tickets for a baseball game in LA area under $100")["data"]

{'action': {'sport': 'baseball',
  'location': 'LA area',
  'price_range': {'price_max': '100'}}}

chain.invoke(
    "I want to see a celtics game in boston somewhere between 20 and 40 dollars per ticket"
)["data"]

{'action': {'sport': 'basketball',
  'location': 'boston',
  'price_range': {'price_max': '40', 'price_min': '20', 'currency': '$'}}}