Voorbeeld: Betalingstracker
Op deze pagina
Een compleet end-to-end-project
In eerdere lessen hebt u elk mechanisme afzonderlijk behandeld: tool-definities, de aanroepcyclus, foutafhandeling en beveiliging. Nu is het tijd om ze samen te voegen. U bouwt een volledige conversationele betalingstracker waarmee gebruikers vragen in natuurlijke taal stellen en het systeem via function calling een Pandas DataFrame ondervraagt. Deze usecase is rechtstreeks ontleend aan de officiële Mistral-documentatie. Het past in ongeveer honderd regels code en belicht de vijf bouwstenen van een echte applicatie: data, bedrijfsfuncties, JSON-specificaties, dispatch en de conversatielus.
De data
Een DataFrame met vijf transacties dekt de interessante scenario’s: een klant met meerdere betalingen, een betaling in behandeling en een mislukte betaling.
import pandas as pd
import json
import os
from mistralai.client import Mistral
from functools import partial
# Transactions DataFrame
data = {
"transaction_id": ["T1001", "T1002", "T1003", "T1004", "T1005"],
"customer_id": ["C001", "C002", "C003", "C002", "C001"],
"payment_amount": [125.50, 89.99, 350.00, 45.00, 210.75],
"payment_date": ["2026-03-15", "2026-03-16", "2026-03-17", "2026-03-17", "2026-03-18"],
"payment_status": ["paid", "paid", "pending", "paid", "failed"]
}
df = pd.DataFrame(data)
Bedrijfsfuncties
Vier functies dekken de typische behoeften voor het volgen van betalingen. De eerste drie werken op één transactie en verschillen in granulariteit: alleen status, alleen datum of alle details. Deze schijnbare redundantie is opzettelijk: hiermee kan het model alleen de benodigde gegevens opvragen, wat onnodige data in de context voorkomt. De vierde functie verlegt het perspectief en werkt op klantniveau.
Let op het gemeenschappelijke contract: alle functies retourneren een JSON-string, ook bij fouten, en alle functies hanteren ontbrekende identifiers in plaats van Pandas een uitzondering te laten gooien op een lege index.
def retrieve_payment_status(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the status of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"status": row["payment_status"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_date(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves the date of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"date": row["payment_date"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def retrieve_payment_details(df: pd.DataFrame, transaction_id: str) -> str:
"""Retrieves all details of a payment."""
if transaction_id in df["transaction_id"].values:
row = df[df["transaction_id"] == transaction_id].iloc[0]
return json.dumps({
"transaction_id": transaction_id,
"customer_id": row["customer_id"],
"amount": float(row["payment_amount"]),
"date": row["payment_date"],
"status": row["payment_status"]
})
return json.dumps({"error": f"Transaction {transaction_id} not found"})
def list_customer_transactions(df: pd.DataFrame, customer_id: str) -> str:
"""Lists all transactions for a given customer."""
customer_df = df[df["customer_id"] == customer_id]
if customer_df.empty:
return json.dumps({"error": f"Customer {customer_id} not found"})
transactions = []
for _, row in customer_df.iterrows():
transactions.append({
"transaction_id": row["transaction_id"],
"amount": float(row["payment_amount"]),
"date": row["payment_date"],
"status": row["payment_status"]
})
return json.dumps({"customer_id": customer_id, "transactions": transactions})
De conversie float(row["payment_amount"]) verdient extra aandacht: zonder deze stap faalt json.dumps op NumPy-types. Dit is het soort detail dat u pas tijdens runtime ontdekt.
JSON-specificaties
Het model ziet geen van de bovenstaande code. Het kent alleen deze beschrijvingen. Door de mogelijke statussen expliciet op te sommen in retrieve_payment_status en het model in elke parameterbeschrijving te herinneren aan het T1001-formaat, stelt u het in staat de juiste functie te kiezen en de identifier correct te extraheren.
tools = [
{
"type": "function",
"function": {
"name": "retrieve_payment_status",
"description": "Retrieves the status of a payment (paid, pending, failed)",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_date",
"description": "Retrieves the date of a payment",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "retrieve_payment_details",
"description": "Retrieves all details of a payment: amount, date, status, customer",
"parameters": {
"type": "object",
"properties": {
"transaction_id": {
"type": "string",
"description": "Transaction identifier (e.g., T1001)"
}
},
"required": ["transaction_id"]
}
}
},
{
"type": "function",
"function": {
"name": "list_customer_transactions",
"description": "Lists all transactions for a given customer",
"parameters": {
"type": "object",
"properties": {
"customer_id": {
"type": "string",
"description": "Customer identifier (e.g., C001)"
}
},
"required": ["customer_id"]
}
}
}
]
De dispatch-woordenlijst
Hier zit de crux: uw functies verwachten df als eerste argument, maar het model zal dit nooit leveren—het weet niet dat het bestaat, en dat is prima. functools.partial lost dit elegant op door het DataFrame vooraf te binden, zodat elke vermelding in de woordenlijst aanroepbaar wordt met alleen de argumenten die het model produceert.
available_functions = {
"retrieve_payment_status": partial(retrieve_payment_status, df),
"retrieve_payment_date": partial(retrieve_payment_date, df),
"retrieve_payment_details": partial(retrieve_payment_details, df),
"list_customer_transactions": partial(list_customer_transactions, df),
}
De conversatielus
Het systeembericht stelt de rol, de taal en de verwachte opmaak voor bedragen vast. De chat-functie orchestreert de rest, en de structuur ervan verdient nauwkeurige aandacht: de while message.tool_calls-lus behandelt één enkele aanroep, meerdere parallelle aanroepen of een keten waarin het model na het zien van het eerste resultaat om een andere functie vraagt. De binnenste lus voert alle aanroepen voor de huidige beurt uit; de buitenste lus roept het model opnieuw aan zolang het tools blijft aanvragen.
client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"
messages = [
{
"role": "system",
"content": "You are a payment tracking assistant. "
"Respond in English. Use the available tools "
"to answer questions about transactions. "
"Format amounts in euros with 2 decimal places."
}
]
def chat(user_input: str) -> str:
"""Complete conversation turn with tool_calls handling."""
messages.append({"role": "user", "content": user_input})
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
# Loop while the model wants to call functions
while message.tool_calls:
messages.append(message)
for tool_call in message.tool_calls:
fn_name = tool_call.function.name
fn_params = json.loads(tool_call.function.arguments)
if fn_name in available_functions:
result = available_functions[fn_name](**fn_params)
else:
result = json.dumps({"error": f"Unknown function {fn_name}"})
messages.append({
"role": "tool",
"name": fn_name,
"content": result,
"tool_call_id": tool_call.id
})
response = client.chat.complete(
model=model, messages=messages, tools=tools
)
message = response.choices[0].message
messages.append(message)
return message.content
Wat de conversatie onthult
Test dit met vier opeenvolgende beurten. De tweede is het meest instructief: “this transaction” bevat geen identifier, toch roept het model retrieve_payment_details aan met T1001. Het lost de anafoor op met behulp van de geschiedenis die in messages bewaard blijft, wat onmogelijk zou zijn als u de lijst bij elke aanroep zou resetten. De vierde beurt toont de andere kant: geen enkele functie zoekt naar mislukte betalingen, maar het model ondervraagt de betreffende klant en filtert het resultaat zelf.
# Turn 1
print(chat("What is the status of payment T1001?"))
# -> "Payment T1001 has status: paid."
# Turn 2
print(chat("Give me all the details for this transaction."))
# -> "Here are the details for payment T1001:
# - Customer: C001
# - Amount: 125.50 euros
# - Date: March 15, 2026
# - Status: paid"
# Turn 3
print(chat("What are all the transactions for customer C002?"))
# -> "Customer C002 has 2 transactions:
# - T1002: 89.99 euros (paid, March 16, 2026)
# - T1004: 45.00 euros (paid, March 17, 2026)"
# Turn 4
print(chat("Are there any failed payments?"))
# -> "Yes, payment T1005 for customer C001 (210.75 euros) failed."
De opmaak van bedragen met een decimaalteken en datums die voluit geschreven zijn, komt uit geen enkele regel code: dit volgt uit de systeemprompt. Dit is de nuttigste les van dit hoofdstuk: de helft van de waargenomen kwaliteit ontstaat in de beschrijvingen en het systeembericht, niet in de aanroepmechanica.
Belangrijkste punten
- Een complete betalingstracker vereist 4 functies die de belangrijkste usecases dekken
functools.partialbindt het DataFrame aan de functies voor een schone dispatch- De
while message.tool_calls-lus behandelt automatisch sequentiële en parallelle aanroepen - Het systeembericht stuurt het model op het gebied van toon, taal en opmaak
- Test met meertraps conversaties om te verifiëren dat het model de context behoudt