🔹 Episodul 4: Primul API Call. Cum conectăm raționamentul din Cloud cu execuția locală

„Am înțeles cum colaborează logica fuzzy cu instrucțiunile rigide prin protocolul Function Calling. Acum este momentul să lăsăm arhitectura de pe hârtie și să asamblăm primele fire electrice: deschidem laboratoarele de test și rulăm primul API Call.”

Bun venit la faza de execuție a proiectului nostru. Lăsăm în urmă schițele conceptuale și construim primul pod digital dintre terminalul tău și inteligența artificială din Cloud.

🔹Obținerea cheii de acces (Google AI Studio)

Pentru ca scripturile tale locale să poată interoga modelul Gemini din Cloud, sistemul are nevoie de o metodă de autentificare securizată. Aceasta nu este o parolă clasică de utilizator, ci o cheie de acces unică numită API Key. Ea acționează ca o amprentă digitală: îi spune serverului din Cloud cine ești și ce drepturi de consum ai.

Ca să pornim de la zero într-un mediu complet controlat, configurarea se face în trei mișcări simple:

• Accesează platforma: Intră pe Google AI Studio folosind contul tău de Google.
• Generează cheia: În panoul de control din partea stângă, identifică și apasă pe butonul “Get API key”, urmat de “Create API key in new project” pentru a primi o cotă curată de test.
• Regulă absolută de siguranță: Platforma îți va afișa pe ecran un șir lung de caractere (ex: AIzaSy...). Copiază acest cod imediat și salvează-l într-un loc securizat. API Key-ul trebuie tratat ca un secret: nu îl publica, nu îl introduce în codul pe care îl distribui și nu îl încărca în depozite publice precum GitHub.

🔹Pregătirea Sandbox-ului izolat (Google Colab)

O regulă de aur în ingineria de sistem spune că nu testezi niciodată un cod neverificat direct în producție sau pe serverul principal. De aceea, înainte de a scrie scriptul pe nodul tău local, vom folosi Google Colab — un mediu de test separat de infrastructura ta locală, în Cloud, unde poți rula Python instantaneu, direct din browser, fără configurări locale.

Pentru a ne asigura că proiectul tău este protejat împotriva scurgerilor de date, configurăm mediul folosind pilonul de securitate al platformei:

• Deschide Google Colab și creează un caiet de lucru nou (New Notebook).
• În bara de unelte din stânga ecranului, caută iconița sub formă de cheie numită “Secrets” (Variabile de mediu).
• Adaugă o variabilă nouă cu numele exact: API_KEY. La secțiunea valoare (Value), lipește codul AIza... generat la Pasul 1.
• Activează comutatorul “Notebook access”. Acest pas este critic: codul tău Python va putea accesa cheia prin sistemul de Secrets, fără ca aceasta să fie introdusă direct în codul notebook-ului.

🔹„Salutul Agentului” (Primul Script Python)

Cu infrastructura de acces securizată, putem rula primul test rapid. Acest script realizează instalarea noii biblioteci oficiale Google GenAI, extrage cheia din sistemul de siguranță al Colab-ului și execută o „strângere de mână” digitală simplă cu modelul din Cloud pentru a valida conexiunea.

Creează o celulă nouă de cod în Colab și introdu următorul script:

# 1. Instalam noul SDK oficial Google GenAI
# Nota: Folosim --quiet pentru a ascunde mesajele lungi de dependente din Colab
!pip install -q --quiet google-genai

# 2. Importam noul client si configuram autentificarea

from google.genai import client
from google.colab import userdata

# Preluam cheia din sistemul izolat "Secrets"

api_key = userdata.get('API_KEY')

# Initializam noul client modern global conform standardului actual

ai = client.Client(api_key=api_key)

# 3. Trimitem o interogare simpla folosind modelul stabil recomandat

response = ai.models.generate_content(
model='gemini-2.5-flash',
contents='Salut! Ești pregătit să fii asistentul meu?',
)

# Afisam raspunsul primit sub forma de text liber

print(response.text)

În momentul în care apeși butonul de rulare (Play) și terminalul îți întoarce un răspuns text coerent (cum ar fi „Yes, absolutely!”), conexiunea de bază este validată. Podul de comunicare directă a fost construit cu succes.

🔹Definirea Contractului și Forțarea Formatului JSON (Function Calling)

Acum că am văzut cum modelul ne răspunde ca un simplu chatbot în text liber, este momentul să facem pasul către ingineria de sistem. Pentru a transforma Gemini într-un Agent capabil să ruleze comenzi rigide pe infrastructura noastră self-hosted, trebuie să-i punem la dispoziție o unealtă tehnică (un contract rigid).

În loc să lăsăm SDK-ul să încerce o conversie automată a unei funcții simple din Python — proces implicit care poate eșua în funcție de pachetele din sistem — vom folosi o abordare explicită și transparentă: declararea explicită a schemei funcției (Function Declaration).

Prin această metodă, îi trimitem modelului Gemini o structură clară de tip JSON Schema în care descriem matematic ce parametri așteaptă serverul nostru local (în cazul nostru, parametrul text numit component). În plus, introducem setarea critică 'mode': 'ANY'. Prin aceasta, îi punem efectiv căluș AI-ului, interzicându-i să ne răspundă cu povești sau text liber, și îl forțăm să genereze un apel de funcție structurat ce conține decizia sa de a apela funcția locală și argumentul extras inteligent din limba română.

Adaugă o a doua celulă de cod în Colab și introdu scriptul de execuție structurală:

# 1. Definim functia locala (Interfata rigida pentru baza de date)
def check_hardware_stock(component: str) -> str:
    # In etapa urmatoare, aceasta va interoga direct baza noastra de date locala
    return f"Stocul local pentru {component} este de 15 unitati."

# 2. Trimitem interogarea si schema explicita catre modelul Gemini

response = ai.models.generate_content(
model='gemini-2.5-flash',
contents='Mai avem module RAM ramase in depozit?',
config={
# Maparea explicita a functiei - abordare clara si controlabila
'tools': [{
'function_declarations': [{
'name': 'check_hardware_stock',
'description': 'Verifica stocul disponibil pentru o anumita componenta hardware.',
'parameters': {
'type': 'OBJECT',
'properties': {
'component': {
'type': 'STRING',
'description': 'Numele componentei hardware (de ex. RAM, SSD).'
}
},
'required': ['component']
}
}]
}],
# Fortam modelul sa raspunda strict prin apel de functie, oprind auto-executia
'tool_config': {
'function_calling_config': {
'mode': 'ANY'
}
}
}
)

# 3. Extragem si afisam decizia structurala reala returnata de AI

if response.function_calls:
for call in response.function_calls:
print(f"Functia de executat: {call.name}")
print(f"Argumente trimise de AI: {call.args}")
else:
print(f"Raspuns text: {response.text}

Când vei rula această a doua celulă, vei observa că AI-ul nu mai răspunde liber, ci generează un apel de funcție structurat, mapând textul utilizatorului pe argumentul de care are nevoie serverul nostru local: de exemplu, Functia de executat: check_hardware_stock și Argumente: {'component': 'RAM'}.

Infrastructura ta a realizat prima conexiune securizată. Mâinile și creierul au început să comunice prin protocoale clare.

Stay Free! Stay Hidden! Stay Autonomous!

⚙️ Appendix: Micro-Curs de Inginerie AI (Clarificări Tehnice)

• API Key (Application Programming Interface Key): Un cod unic utilizat de un program computerizat pentru a se identifica în fața unui API extern, funcționând ca o metodă de autentificare. API Key-ul trebuie tratat ca un secret și protejat împotriva expunerii accidentale.
• Sandbox: Un mediu de calcul separat de infrastructura de producție, în interiorul căruia codul software poate fi rulat și testat fără a fi executat direct pe sistemul principal.
• Secrets / Environment Variables: Variabile dinamice stocate în afara codului sursă, utilizate pentru a transmite credențiale, API Keys, parole sau alte secrete către o aplicație, reducând riscul expunerii lor accidentale pe platforme publice precum GitHub.
• JSON Request (JavaScript Object Notation): Un format standardizat pentru reprezentarea și transferul datelor, bazat pe text structurat în perechi cheie-valoare, ușor de citit de oameni și de procesat de calculatoare. În arhitectura noastră, astfel de structuri pot transporta informații între aplicația locală și serviciul din Cloud.
• Function Calling automatizat în SDK: În versiunile mai noi ale SDK-ului Google GenAI, o parte din mecanismul pe care l-am construit manual în acest laborator poate fi automatizată. SDK-ul poate porni de la o funcție Python și poate genera structura necesară pentru ca modelul să o utilizeze ca unealtă, iar în anumite moduri poate gestiona și ciclul de apelare și execuție. În laboratorul nostru am ales intenționat varianta explicită: am definit manual contractul, am lăsat modelul să genereze apelul de funcție și am executat funcția local. Astfel putem vedea clar ce se întâmplă între „creierul” din Cloud și „mâinile” Agentului local.