🔹 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 fizic podul digital dintre terminalul tău și inteligența artificială aplicată.

🔹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 criptografică 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 fișier local securizat. După ce ai închis acea fereastră, Google ascunde cheia din motive de securitate și nu o mai poți recupera; va trebui să generezi alta.

🔹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 complet izolat (sandbox) î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 apela cheia în spate, dar caracterele secrete nu vor apărea niciodată scrise în clar pe ecran sau în interiorul fișierului.

🔹„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 standardul stabil de producție: declararea explicită a schemei funcției (Function Declaration).

By 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, pilonul 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ă ne returneze **exclusiv un obiect structural JSON** 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 - standardul de productie pentru siguranta API-ului
        '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 (JSON), 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 vorbește liber, ci livrează instant comanda JSON brută pe ecran, mapând textul utilizatorului pe argumentul exact de care are nevoie serverul nostru local: 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ă sigură de autentificare fără a expune credențialele de utilizator.

• Sandbox: Un mediu de calcul izolat, separat de sistemul de operare de producție, în interiorul căruia codul software poate fi rulat și testat în siguranță, fără riscul de a altera infrastructura principală.
• Secrets / Environment Variables: Variabile dinamice din sistem stocate în afara codului sursă, utilizate pentru a transmite credențiale sau chei criptografice către o aplicație în mod securizat, prevenind expunerea lor accidentală pe platforme publice precum GitHub.
• JSON Request (JavaScript Object Notation): Un format standardizat de stocare și transfer de date, bazat pe text simplu (structurat în perechi cheie-valoare), extrem de ușor de citit de către oameni și ușor de parsat de către calculatoare, folosit aici ca punte de comunicare între Cloud și scriptul local.