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

Eżempju Prattiku: CRM Awtomatizzat

Lezzjoni 13 / 14 Aġġornat 2 ta’ Novembru 2026 Zviluppatur
F'din il-paġna
  1. CRM Imħaddem mill-Konversazzjoni
  2. Il-Bażi tad-Data Simulata
  3. Il-Funzjonijiet CRUD
  4. Speċifikazzjonijiet tal-Għodda JSON
  5. Id-Dispatch u ċ-Ċiklu
  6. Erba’ Xenarji u X’Jgħallmuna
  7. Il-Passaġġ għall-Produzzjoni Mingħajr Ma Tikteb Kollox Mill-Ġdid
  8. Punti Ewlenin

CRM Imħaddem mill-Konversazzjoni

Immaġina CRM fejn ir-rappreżentanti tal-bejgħ m’għandhomx għalfejn jinnavigaw interfaċċi kumplessi. Huma jitkellmu ma’ assistent li awtomatikament joħloq, jaġġorna, u jirkupra kuntatti. Dan huwa eżattament dak li l-”function calling” jippermettilek tibni. Id-differenza mit-traċċatur tal-ħlasijiet fil-lezzjoni preċedenti hija sinifikanti: sa issa, il-mudell kien biss jaqra d-data. Hawnhekk, huwa jikteb id-data, li tbiddel il-fokus tal-eżerċizzju lejn il-validazzjoni, il-konferma, u l-ġestjoni tad-duplikati.

Inti se timplimenta CRM konversazzjonali b’operazzjonijiet CRUD (Create, Read, Update, Delete) fuq bażi tad-data ta’ kuntatti.

Il-Bażi tad-Data Simulata

Dizzjunarju Python iservi bħala l-bażi tad-data għal din id-dimostrazzjoni. Żewġ kuntatti huma biżżejjed: klijent wieħed u prospett wieħed. Din il-konfigurazzjoni tippermettilna nittestjaw tranżizzjoni ta’ status aktar tard fil-lezzjoni.

import json
import os
from mistralai.client import Mistral

# In-memory contact database (in production: PostgreSQL, MongoDB, etc.)
contacts_db = {
    "CT001": {
        "name": "Marie Dupont",
        "email": "[email protected]",
        "company": "TechCorp",
        "role": "Chief Technology Officer",
        "phone": "+33 6 12 34 56 78",
        "status": "client",
        "notes": "Interested in the enterprise solution"
    },
    "CT002": {
        "name": "Pierre Martin",
        "email": "[email protected]",
        "company": "StartupIO",
        "role": "CEO",
        "phone": "+33 6 98 76 54 32",
        "status": "prospect",
        "notes": "Meeting scheduled for April"
    }
}

next_id = 3  # Counter for new contacts

Il-Funzjonijiet CRUD

get_contact u search_contacts jimmaniġġjaw l-operazzjonijiet ta’ qari. Dan tal-aħħar jaċċetta argument ta’ qasam ta’ tfittxija biex jevita l-ħolqien ta’ funzjonijiet multipli kważi identiċi. create_contact hija l-ewwel funzjoni li timmodifika l-istat tas-sistema, u turi regola li spiss tiġi injorata fil-modalitajiet konversazzjonali: il-verifiki tal-unikità għandhom ikunu fil-kodiċi tiegħek, qatt fil-prompt mogħti lill-mudell. Xejn ma jipprevjeni lir-rappreżentant tal-bejgħ milli jiddetta l-istess kuntatt darbtejn; il-verifika tal-email fil-bidu tal-funzjoni tirritorna duplicate_email bl-ID eżistenti, u tippermetti lill-mudell jispjega r-rifjut b’mod preċiż.

update_contact tuża approċċ ta’ oqsma opzjonali: biss l-oqsma pprovduti jiġu mmodifikati, u l-funzjoni tirritorna lista ta’ dak li nbidel effettivament. Din il-lista mhix dekorattiva—tippermetti lill-assistent jikkonferma l-modifika b’sentenza eżatta minflok “magħmul” vag.

def get_contact(contact_id: str) -> str:
    """Retrieves information for a contact."""
    if contact_id in contacts_db:
        contact = contacts_db[contact_id].copy()
        contact["contact_id"] = contact_id
        return json.dumps(contact, ensure_ascii=False)
    return json.dumps({"error": f"Contact {contact_id} not found"})


def search_contacts(query: str, field: str = "name") -> str:
    """Searches for contacts by name, company, or status."""
    results = []
    for cid, contact in contacts_db.items():
        if field in contact and query.lower() in contact[field].lower():
            entry = contact.copy()
            entry["contact_id"] = cid
            results.append(entry)

    if results:
        return json.dumps({"results": results, "count": len(results)},
                          ensure_ascii=False)
    return json.dumps({"results": [], "count": 0,
                        "message": f"No contact found for '{query}' in '{field}'"})


def create_contact(name: str, email: str, company: str,
                   role: str = "", phone: str = "",
                   status: str = "prospect", notes: str = "") -> str:
    """Creates a new contact in the CRM."""
    global next_id

    # Check if email already exists
    for cid, contact in contacts_db.items():
        if contact["email"].lower() == email.lower():
            return json.dumps({
                "error": "duplicate_email",
                "message": f"A contact with this email already exists: {cid}"
            })

    contact_id = f"CT{next_id:03d}"
    next_id += 1

    contacts_db[contact_id] = {
        "name": name,
        "email": email,
        "company": company,
        "role": role,
        "phone": phone,
        "status": status,
        "notes": notes
    }

    return json.dumps({
        "success": True,
        "contact_id": contact_id,
        "message": f"Contact {name} created with ID {contact_id}"
    }, ensure_ascii=False)


def update_contact(contact_id: str, **fields) -> str:
    """Updates one or more fields of an existing contact."""
    if contact_id not in contacts_db:
        return json.dumps({"error": f"Contact {contact_id} not found"})

    updated_fields = []
    for key, value in fields.items():
        if key in contacts_db[contact_id]:
            contacts_db[contact_id][key] = value
            updated_fields.append(key)

    if updated_fields:
        return json.dumps({
            "success": True,
            "contact_id": contact_id,
            "updated_fields": updated_fields,
            "message": f"Contact {contact_id} updated: {', '.join(updated_fields)}"
        }, ensure_ascii=False)

    return json.dumps({"error": "No valid fields to update"})

Il-parametru ensure_ascii=False preżenti f’diversi ritorni mhuwiex dettall kożmetiku: mingħajru, “Interested” isir sekwenza ta’ karattri Unicode escape fil-kuntest tal-mudell, li huwa inqar leġibbli u aktar għali f’termini ta’ tokens.

Speċifikazzjonijiet tal-Għodda JSON

Żewġ mekkaniżmi jġorru l-biċċa l-kbira tal-affidabbiltà hawnhekk. L-enum fuq status jipprevjeni lill-mudell milli jinventa valuri: irid jagħżel fost prospect, client, partner, u inactive, u b’hekk jipproteġi l-integrità tad-data tiegħek mingħajr validazzjoni addizzjonali. L-array required jagħmel il-bqija billi jiddistingwi l-oqsma obbligatorji minn dawk opzjonali—għal create_contact, kuntatt mingħajr isem, email, jew kumpanija ma jagħmilx sens, filwaqt li numru tat-telefon jista’ jiġi aktar tard.

tools = [
    {
        "type": "function",
        "function": {
            "name": "get_contact",
            "description": "Retrieves all information for a contact by ID",
            "parameters": {
                "type": "object",
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "description": "Contact ID (e.g., CT001)"
                    }
                },
                "required": ["contact_id"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "search_contacts",
            "description": "Searches for contacts by name, company, or status",
            "parameters": {
                "type": "object",
                "properties": {
                    "query": {
                        "type": "string",
                        "description": "Search term"
                    },
                    "field": {
                        "type": "string",
                        "enum": ["name", "company", "status", "role"],
                        "description": "Field to search in (default: name)"
                    }
                },
                "required": ["query"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "create_contact",
            "description": "Creates a new contact in the CRM",
            "parameters": {
                "type": "object",
                "properties": {
                    "name": {
                        "type": "string",
                        "description": "Full name of the contact"
                    },
                    "email": {
                        "type": "string",
                        "description": "Email address of the contact"
                    },
                    "company": {
                        "type": "string",
                        "description": "Company name"
                    },
                    "role": {
                        "type": "string",
                        "description": "Job title or function within the company"
                    },
                    "phone": {
                        "type": "string",
                        "description": "Phone number"
                    },
                    "status": {
                        "type": "string",
                        "enum": ["prospect", "client", "partner", "inactive"],
                        "description": "Contact status"
                    },
                    "notes": {
                        "type": "string",
                        "description": "Free-form notes about the contact"
                    }
                },
                "required": ["name", "email", "company"]
            }
        }
    },
    {
        "type": "function",
        "function": {
            "name": "update_contact",
            "description": "Updates information for an existing contact",
            "parameters": {
                "type": "object",
                "properties": {
                    "contact_id": {
                        "type": "string",
                        "description": "ID of the contact to modify (e.g., CT001)"
                    },
                    "name": {"type": "string", "description": "New name"},
                    "email": {"type": "string", "description": "New email"},
                    "company": {"type": "string", "description": "New company"},
                    "role": {"type": "string", "description": "New job title"},
                    "phone": {"type": "string", "description": "New phone number"},
                    "status": {
                        "type": "string",
                        "enum": ["prospect", "client", "partner", "inactive"],
                        "description": "New status"
                    },
                    "notes": {"type": "string", "description": "New notes"}
                },
                "required": ["contact_id"]
            }
        }
    }
]

Id-Dispatch u ċ-Ċiklu

Peress li l-funzjonijiet ma jiddependu fuq l-ebda oġġett estern, id-dizzjunarju tad-dispatch jonqos għal mappa diretta. Il-messaġġ tas-sistema, madankollu, iġorr żewġ restrizzjonijiet komportamentali nieqsa mill-kodiċi: ikkonferma kull azzjoni ta’ ħolqien jew aġġornament bid-dettalji, u itlob informazzjoni nieqsa qabel ma toħloq kuntatt. Mingħajr dik it-tieni istruzzjoni, il-mudell għandu t-tendenza li jimla l-oqsma meħtieġa b’valuri plawżibbli.

available_functions = {
    "get_contact": get_contact,
    "search_contacts": search_contacts,
    "create_contact": create_contact,
    "update_contact": update_contact,
}

client = Mistral(api_key=os.environ["MISTRAL_API_KEY"])
model = "mistral-large-latest"

messages = [
    {
        "role": "system",
        "content": "You are a CRM assistant. You help sales reps "
                   "manage their contacts. Respond in English. "
                   "When you create or modify a contact, confirm "
                   "the action with details. Request missing "
                   "information before creating a contact."
    }
]

Erba’ Xenarji u X’Jgħallmuna

L-ewwel xenarju juri lill-mudell jagħżel field="company" waħdu anke jekk l-utent ma speċifika xejn: l-enum tal-iskema pprovda l-għażliet, u l-formulazzjoni tal-mistoqsija għamlet il-bqija. It-tieni jipprovdi informazzjoni f’taħlita, mingħajr tikketta, u l-mudell jiddistribwixxihom b’mod korrett fost l-isem, l-email, il-kumpanija, u t-titlu. It-tielet huwa l-aktar rikk: “Switch Pierre Martin to client” ma fih l-ebda ID, allura l-mudell irid jgħaqqad tfittxija u mbagħad aġġornament, u jiddeduċi n-nota kuntestwali matul it-triq. Ir-raba’ jfakkarna li l-mudell jista’ jerġa’ juża funzjoni mill-użu litterali tagħha biex iwieġeb mistoqsija ta’ għadd.

# Scenario 1: Search for a contact
chat("Find me contacts at TechCorp")
# -> The model calls search_contacts(query="TechCorp", field="company")
# -> "I found 1 contact at TechCorp: Marie Dupont (CT001),
#     Chief Technology Officer, status client."

# Scenario 2: Create a contact
chat("Add a new contact: Sophie Laurent, [email protected], "
     "DataViz, Data Scientist")
# -> The model calls create_contact(name="Sophie Laurent",
#     email="[email protected]", company="DataViz", role="Data Scientist")
# -> "Contact created successfully! Sophie Laurent (CT003) has been added
#     as a prospect at DataViz."

# Scenario 3: Update a status
chat("Switch Pierre Martin to client, he just signed")
# -> The model first searches for Pierre Martin, then calls
#    update_contact(contact_id="CT002", status="client",
#                   notes="Contract signed in April 2026")
# -> "Pierre Martin (CT002) is now marked as a client.
#     I added a note about the contract signature."

# Scenario 4: Question without a dedicated function
chat("How many prospects do we have?")
# -> The model calls search_contacts(query="prospect", field="status")
# -> "You currently have 1 prospect: Sophie Laurent at DataViz."

Il-Passaġġ għall-Produzzjoni Mingħajr Ma Tikteb Kollox Mill-Ġdid

Id-dizzjunarju fil-memorja ovvjament jisparixxi malli jkun hemm utenti multipli. Madankollu, li tissostitwixxih bi bażi tad-data reali jeħtieġ li tmiss saff wieħed biss: il-funzjoni tistaqsi lill-ORM jew lill-API tal-CRM tiegħek u xorta tirritorna l-istess stringa JSON.

# Functions call your CRM's ORM or API
def get_contact_production(contact_id: str) -> str:
    """Production version with PostgreSQL."""
    contact = db.session.query(Contact).filter_by(id=contact_id).first()
    if contact:
        return json.dumps(contact.to_dict(), ensure_ascii=False)
    return json.dumps({"error": f"Contact {contact_id} not found"})

Il-bqija tal-kodiċi—l-għodod, id-dispatch, iċ-ċiklu tal-konversazzjoni—jibqa’ identiku. Din hija s-saħħa ta’ din l-arkitettura: biss il-funzjonijiet tal-loġika tan-negozju jinbidlu, u s-saff konversazzjonali jibqa’ mhux konxju tal-għażliet ta’ persistenza tiegħek.

Punti Ewlenin

  • Il-”function calling” ibiddel LLM f’interfaċċa naturali għal CRM
  • L-operazzjonijiet CRUD jimmapjaw direttament ma’ funzjonijiet b’JSON Schema
  • Il-mudell jista’ jgħaqqad tfittxija u mbagħad aġġornament fi ħdan konversazzjoni waħda
  • L-arkitettura hija disakkoppjata: ibdel il-bażi tad-data mingħajr ma tmiss il-loġika tal-konversazzjoni
  • Il-messaġġ tas-sistema huwa kruċjali biex jiggwida lill-mudell dwar il-konfermi u l-informazzjoni nieqsa