Aqbeż għall-kontenut ewlieni
Malti— Agħżel lingwa
Menu

Eżempju Prattiku: Traċċatur tal-Ħlasijiet

Lezzjoni 12 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. Proġett Sħiħ Minn Truf għal Truf
  2. Id-Data
  3. Funzjonijiet tan-Negozju
  4. Speċifikazzjonijiet JSON
  5. Id-Dizzjunarju tad-Dispaċċ
  6. Iċ-Ċiklu tal-Konversazzjoni
  7. X’Jikxef il-Konversazzjoni
  8. Punti Ewlenin

Proġett Sħiħ Minn Truf għal Truf

Il-lezzjonijiet preċedenti iżolaw kull mekkaniżmu: id-definizzjonijiet tal-għodod, iċ-ċiklu tas-sejħa, l-immaniġġjar tal-iżbalji, u s-sigurtà. Issa wasal iż-żmien biex tgħaqqadhom flimkien. Se tibni traċċatur konversazzjonali tal-ħlasijiet sħiħ fejn l-utenti jagħmlu mistoqsijiet b’lingwa naturali u s-sistema tistaqsi DataFrame tal-Pandas permezz tas-sejħa tal-funzjonijiet. Dan il-każ ta’ użu jiġi direttament mid-dokumentazzjoni uffiċjali ta’ Mistral. Jidħol f’madwar mitt linwa waqt li jesponi l-ħames blokok tal-bini ta’ applikazzjoni reali: id-data, il-funzjonijiet tan-negozju, l-ispeċifikazzjonijiet JSON, id-dispaċċ, u ċ-ċiklu tal-konversazzjoni.

Id-Data

DataFrame b’ħames tranżazzjonijiet ikopri x-xenarji interessanti: klijent b’ħlasijiet multipli, ħlas pendenti, u ħlas fallut.

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)

Funzjonijiet tan-Negozju

Erba’ funzjonijiet ikopru l-ħtiġijiet tipiċi tat-traċċar tal-ħlasijiet. L-ewwel tlieta jaħdmu fuq tranżazzjoni waħda u jvarjaw skont il-granularità: biss l-istatus, biss id-data, jew id-dettalji sħaħ. Din ir-ridondanza apparenti hija deliberata—tippermetti lill-mudell jitlob biss dak li għandu bżonn, u b’hekk inaqqas data mhux meħtieġa fil-kuntest. Ir-raba’ funzjoni tbiddel il-perspettiva u topera skont il-klijent.

Innota l-kuntratt komuni: kollha jirritornaw stringa JSON, anke meta jfallu, u kollha jimmaniġġjaw identifikaturi nieqsa minflok ma jħallu lill-Pandas iqajjem eċċezzjoni fuq indiċi vojt.

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})

Il-konverżjoni float(row["payment_amount"]) teħtieġ ħarsa oħra: mingħajrha, json.dumps ifalli fuq it-tipi ta’ NumPy. Dan huwa d-dettal li tasal biex taqbdu biss waqt ir-runtime.

Speċifikazzjonijiet JSON

Il-mudell ma jarax l-ebda kodiċi hawn fuq. Huwa jaf biss b’dawn id-deskrizzjonijiet. Li telenka b’mod espliċitu l-istatus possibbli f’retrieve_payment_status u tfakkar lill-mudell bil-format T1001 f’kull deskrizzjoni ta’ parametru jippermettilu jagħżel il-funzjoni t-tajba u jipproċessa l-identifikatur korrettament.

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"]
            }
        }
    }
]

Id-Dizzjunarju tad-Dispaċċ

Hawnhekk hemm il-qabda: il-funzjonijiet tiegħek jistennew df bħala l-ewwel argument, iżda l-mudell qatt ma se jipprovdih—huwa ma jafx li jeżisti, u dan huwa tajjeb. functools.partial isolvi dan b’mod eleganti billi jorbot minn qabel id-DataFrame, sabiex kull entrata fid-dizzjunarju ssir callable bl-argumenti biss li jipproduċi l-mudell.

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),
}

Iċ-Ċiklu tal-Konversazzjoni

Il-messaġġ tas-sistema jistabbilixxi r-rwol, il-lingwa, u l-iffurmatjar mistenni għall-ammonti. Il-funzjoni chat torganizza l-bqija, u l-istruttura tagħha teħtieġ attenzjoni mill-qrib: iċ-ċiklu while message.tool_calls jimmaniġġja sejħa waħda, sejħiet paralleli multipli, jew katina fejn il-mudell jitlob funzjoni oħra wara li jara l-ewwel riżultat. Iċ-ċiklu ta’ ġewwa jesegwixxi s-sejħiet kollha għad-dawra attwali; iċ-ċiklu ta’ barra jerġa’ jsejjaħ lill-mudell sakemm ikompli jitlob għodod.

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

X’Jikxef il-Konversazzjoni

Ittestja dan b’erba’ dawriet konsekuttivi. It-tieni wieħed huwa l-aktar istruttiv: “din it-tranżazzjoni” ma fiha l-ebda identifikatur, madankollu l-mudell isejjaħ retrieve_payment_details b’T1001. Huwa solva l-anafora bl-użu tal-istorja ppreservata f’messages, li kien ikun impossibbli kieku rrisettajt il-lista f’kull sejħa. Ir-raba’ dawra turi n-naħa l-oħra: l-ebda funzjoni ma tfittex ħlasijiet falluti, iżda l-mudell jistaqsi lill-klijent rilevanti u jiffiltra r-riżultat innifsu.

# 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."

L-iffurmatjar tal-ammonti b’punt deċimali u d-dati miktuba b’mod sħiħ ma jiġi minn l-ebda linja ta’ kodiċi: dan isegwi mill-prompt tas-sistema. Din hija l-aktar konklużjoni utli minn dan il-kapitlu—nofs il-kwalità perċepita sseħħ fid-deskrizzjonijiet u fil-messaġġ tas-sistema, mhux fil-mekkaniżmi tas-sejħa.

Punti Ewlenin

  • Traċċatur tal-ħlasijiet sħiħ jeħtieġ 4 funzjonijiet li jkopru l-każijiet ta’ użu ewlenin
  • functools.partial jorbot id-DataFrame mal-funzjonijiet għal dispaċċ nadif
  • Iċ-ċiklu while message.tool_calls jimmaniġġja awtomatikament sejħiet sekwenzjali u paralleli
  • Il-messaġġ tas-sistema jiggwida lill-mudell dwar it-ton, il-lingwa, u l-iffurmatjar
  • Ittestja b’konversazzjonijiet multi-dawra biex tivverifika li l-mudell iżomm il-kuntest