Explicaţie pas cu pas a scriptului „Claim‑Review Pipeline”

Mai jos găseşti o descriere detaliată a fiecărui bloc de cod, a scopului său și a bibliotecilor utilizate. Am păstrat ordinea cronologică a execuţiei, astfel încât să poţi înţelege cum se trece de la un articol brut la un fişier JSON‑LD cu obiecte ClaimReview.

1️⃣ Importuri & configurare iniţială

Notă: Dacă nu ai instalat pandas, tqdm sau requests, le poţi adăuga cu pip install pandas tqdm requests.

2️⃣ Configurarea variabilelor globale

ARTICLE_URL = " https://exemplu.ro/articol.html" 
WIKIDATA_ENDPOINT = " https://www.wikidata.org/w/api.php" 
GOOGLE_FACTCHECK_ENDPOINT = " https://factchecktools.googleapis.com/v1alpha1/claims:search" 
GOOGLE_API_KEY = "YOUR_GOOGLE_API_KEY"

• ARTICLE_URL – adresa web a articolului pe care îl vom analiza.
• WIKIDATA_ENDPOINT – endpoint‑ul API‑ului Wikidata (folosit pentru interogări SPARQL / căutare de entităţi).
• GOOGLE_FACTCHECK_ENDPOINT – endpoint‑ul Google Fact‑Check Tools (necesită cheia API).
• GOOGLE_API_KEY – cheia personală pentru a accesa Google Fact‑Check API.

3️⃣ Funcţia wikidata_check(claim)

def wikidata_check(claim: str) -> dict | None:
    # Construieşte interogarea SPARQL pentru a căuta claim‑ul în Wikidata
    query = f"""
    SELECT ?item WHERE {{
      ?item ?label "{claim}"@en .
    }}
    LIMIT 1
    """
    params = {"action": "query", "format": "json", "list": "search", "srsearch": claim}
    resp = requests.get(WIKIDATA_ENDPOINT, params=params, timeout=10)
    if resp.ok:
        data = resp.json()
        if data.get("search"):
            return data["search"][0]          # returnează primul rezultat găsit
    return None

• Scop: Verifică dacă afirmaţia (claim) există ca entitate în Wikidata.
• Ce face: Trimite o cerere GET cu parametrii de căutare; dacă există rezultate, returnează primul (dicţionar cu title, snippet, url etc.). Dacă nu, returnează None.
• Observaţii: În codul original se poate folosi SPARQL, dar aici se foloseşte metoda search simplificată.

4️⃣ Funcţia google_factcheck_check(claim)

def google_factcheck_check(claim: str) -> dict | None:
    params = {
        "query": claim,
        "key": GOOGLE_API_KEY,
        "languageCode": "ro",   # limba română
    }
    resp = requests.get(GOOGLE_FACTCHECK_ENDPOINT, params=params, timeout=10)
    if resp.ok:
        data = resp.json()
        if data.get("claims"):
            return data["claims"][0]       # primul claim găsit în Google Fact‑Check
    return None

• Scop: Caută afirmaţia în baza de date Google Fact‑Check.
• Ce face: Trimite o cerere GET cu query = claim și cheia API. Dacă există rezultate, returnează primul obiect claim (conţine rating, URL, etc.).
• Important: Pentru a funcţiona trebuie să ai un cont Google Cloud și să activezi API‑ul Fact Check Tools.

5️⃣ Funcţia build_claimreview(...)

def build_claimreview(
    claim: str,
    rating: str,
    review_url: str,
    author_name: str,
    publisher_name: str,
) -> dict:
    return {
        "@type": "ClaimReview",
        "datePublished": datetime.utcnow().strftime("%Y-%m-%dT%H:%M:%SZ"),
        "url": review_url,
        "author": {"@type": "Organization", "name": author_name},
        "publisher": {"@type": "Organization", "name": publisher_name},
        "claimReviewed": claim,
        "reviewRating": {
            "@type": "Rating",
            "ratingValue": rating,
            "bestRating": "True",
            "worstRating": "False",
        },
    }

• Scop: Construieşte un obiect JSON‑LD conform specificaţiei ClaimReview din schema.org.
• Câmpuri cheie:
• @type: tipul schema (ClaimReview).
• datePublished: data curentă în format ISO‑8601 (UTC).
• url: link‑ul către sursa de verificare (Wikidata sau Google Fact‑Check).
• author & publisher: informaţii despre entitatea care a făcut verificarea.
• claimReviewed: textul afirmaţiei originale.
• reviewRating: ratingul (ex. "True", "False" sau "Unrated"). bestRating/worstRating sunt setate pentru a indica ce valoare reprezintă adevărat/fals.

6️⃣ Funcţia main()

def main():
    # 1️⃣  Citeşte articolul și extrage claim‑urile
    df_claims = pd.read_csv("claims.csv")   # sau orice altă sursă de date
    claimreview_items = []

    # 2️⃣  Parcurge fiecare claim cu bară de progres
    for _, row in tqdm(df_claims.iterrows(),
                       total=len(df_claims),
                       desc="Verificare claim‑uri"):
        claim = row["claim_raw"]

        # 3️⃣  Caută în Wikidata
        wikidata_res = wikidata_check(claim)
        if wikidata_res:
            rating = "True"
            source = f" https://www.wikidata.org/wiki/{wikidata_res ['item']['value'].split('/')[-1]}"
        else:
            # 4️⃣  Dacă nu există în Wikidata, încearcă Google Fact‑Check
            google_res = google_factcheck_check(claim)
            if google_res:
                rating = google_res.get("textualRating", "Unrated")
                source = google_res.get("claimReview", [{}])[0].get("url", "")
            else:
                rating = "Unrated"
                source = ARTICLE_URL

        # 5️⃣  Construiește obiectul ClaimReview
        cr = build_claimreview(
            claim=claim,
            rating=rating,
            review_url=source,
            author_name="Fact‑Check Bot",
            publisher_name="MyFactCheck.org",
        )
        claimreview_items.append(cr)

    # 6️⃣  Serializare JSON‑LD
    output = {
        "@context": " https://schema.org", 
        "@graph": claimreview_items,
    }
    jsonld_str = json.dumps(output, indent=2, ensure_ascii=False)

    # 7️⃣  Salvează în fişier cu timestamp
    out_path = f"claimreview_{datetime.utcnow().strftime('%Y%m%d_%H%M%S')}.jsonld"
    with open(out_path, "w", encoding="utf-8") as f:
        f.write(jsonld_str)

    print(f"✅ Pipeline terminat - {len(claimreview_items)} ClaimReview salvate în {out_path}")

Etapele detaliate

7️⃣ Ce biblioteci / instrumente sunt folosite și de ce?

8️⃣ Cum poţi rula scriptul

1. Instalează dependenţele

„`bash
pip install pandas tqdm requests
„`

2. Pregăteşte fişierul claims.csv – trebuie să conţină cel puţin coloana claim_raw. Exemple:

„`csv
claim_raw
„Vaccinul COVID‑19 conţine microcipuri”
„Păsările migratoare aduc gripă”
„`

3. Setează variabilele de configurare – înlocuieşte ARTICLE_URL, GOOGLE_API_KEY și eventual alte endpoint‑uri dacă foloseşti altă versiune.

4. Rulează scriptul

„`bash
python claim_review_pipeline.py
„`

5. Verifică rezultatul – vei găsi un fişier claimreview_YYYYMMDD_HHMMSS.jsonld în directorul curent. Poţi deschide fişierul cu un editor de text sau îl poţi încărca într‑un validator JSON‑LD pentru a te asigura că respectă schema.org.

9️⃣ Posibile îmbunătăţiri / extensii

| Cache local | Salvează răspunsurile