Preskoči na glavni sadržaj
Hrvatski— Odaberite jezik
Izbornik

Primjer iz prakse: Praćenje plaćanja

Lekcija 12 od 14 Ažurirano 2. studenoga 2026. Programer
Na ovoj stranici
  1. Potpuni projekt od kraja do kraja
  2. Podaci
  3. Poslovne funkcije
  4. JSON specifikacije
  5. Rječnik za usmjeravanje
  6. Petlja razgovora
  7. Što razgovor otkriva
  8. Ključne točke

Potpuni projekt od kraja do kraja

Prethodne lekcije izolirale su svaki mehanizam zasebno: definicije alata, ciklus poziva, rukovanje greškama i sigurnost. Sada je vrijeme da ih sastaviš. Izgradit ćeš potpuni konverzacijski sustav za praćenje plaćanja u kojem korisnici postavljaju pitanja prirodnim jezikom, a sustav upituje Pandas DataFrame putem poziva funkcija. Ovaj slučaj uporabe izravno proizlazi iz službene dokumentacije Mistrala. Stane u stotinjak redaka, a otkriva pet gradivnih blokova stvarne aplikacije: podatke, poslovne funkcije, JSON specifikacije, usmjeravanje i petlju razgovora.

Podaci

DataFrame s pet transakcija pokriva zanimljive scenarije: kupca s više plaćanja, plaćanje na čekanju i neuspjelo plaćanje.

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)

Poslovne funkcije

Četiri funkcije pokrivaju tipične potrebe praćenja plaćanja. Prve tri rade na jednoj transakciji i razlikuju se po granuliranosti: samo status, samo datum ili puni detalji. Ova prividna suvišnost je namjerna – omogućuje modelu da zatraži samo ono što mu treba, smanjujući nepotrebne podatke u kontekstu. Četvrta mijenja perspektivu i radi po kupcu.

Obrati pažnju na zajednički ugovor: sve vraćaju JSON niz, čak i kod neuspjeha, i sve rukuju nedostajućim identifikatorima umjesto da dopuste Pandasu da baci iznimku na prazan indeks.

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

Konverzija float(row["payment_amount"]) zaslužuje drugi pogled: bez nje, json.dumps ne uspijeva na NumPy tipovima. To je ona vrsta detalja koju uhvatiš tek tijekom izvršavanja.

JSON specifikacije

Model ne vidi ništa od gornjeg koda. On poznaje samo ove opise. Eksplicitno navođenje mogućih statusa u retrieve_payment_status i podsjećanje modela na format T1001 u svakom opisu parametra omogućuje mu da odabere pravu funkciju i ispravno izvuče identifikator.

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

Rječnik za usmjeravanje

Evo kvake: tvoje funkcije očekuju df kao prvi argument, ali model ga nikada neće pružiti – on ne zna da postoji, i to je u redu. functools.partial to elegantno rješava prethodnim vezanjem DataFramea, tako da svaki unos u rječniku postane poziviv samo s argumentima koje model proizvede.

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

Petlja razgovora

Sistemska poruka postavlja ulogu, jezik i očekivano formatiranje iznosa. Funkcija chat orchestrira ostatak, a njezina struktura zaslužuje pomnu pažnju: petlja while message.tool_calls rukuje jednim pozivom, više paralelnih poziva ili lancem gdje model zatraži drugu funkciju nakon što vidi prvi rezultat. Unutarnja petlja izvršava sve pozive za trenutni okret; vanjska petlja ponovno poziva model sve dok on nastavlja tražiti alate.

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

Što razgovor otkriva

Isprobaj ovo s četiri uzastopna okreta. Drugi je najpoučniji: „ova transakcija“ ne sadrži identifikator, ipak model poziva retrieve_payment_details s T1001. Razriješio je anaforu koristeći povijest sačuvanu u messages, što bi bilo nemoguće da resetiraš popis pri svakom pozivu. Četvrti okret pokazuje drugu stranu: nijedna funkcija ne traži neuspjela plaćanja, ali model upituje relevantnog kupca i sam filtrira rezultat.

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

Formatiranje iznosa s decimalnom točkom i datuma napisanih u punom obliku ne proizlazi ni iz jednog retka koda: to slijedi iz sistemske poruke. Ovo je najkorisniji zaključak ovog poglavlja – polovica percipirane kvalitete događa se u opisima i sistemskoj poruci, a ne u mehanici pozivanja.

Ključne točke

  • Potpun tracker plaćanja zahtijeva 4 funkcije koje pokrivaju glavne slučajeve uporabe
  • functools.partial veže DataFrame na funkcije za čisto usmjeravanje
  • Petlja while message.tool_calls automatski rukuje sekvencijalnim i paralelnim pozivima
  • Sistemska poruka vodi model glede tona, jezika i formatiranja
  • Testiraj s višestrukim razgovorima kako bi verificirao da model održava kontekst