Magisterium AI jesponi l-iskills li ġejjin permezz tal-protokoll A2A. Speċifika l-iskill li trid tuża permezz ta' metadata.skillId fuq il-messaġġ. Jekk skillId jitħalla barra, jintuża catholic_qa bħala default.

L-iskills kollha jiġu msejħa permezz tal-metodu JSON-RPC message/send.

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "message/send",
  "params": {
    "message": {
      "role": "user",
      "messageId": "unique-id",
      "kind": "message",
      "parts": [{ "kind": "text", "text": "your query here" }],
      "metadata": { "skillId": "document_search" }
    }
  }
}

Ir-risposti dejjem jiġu lura bħala Task (kind: "task") b'status.state: "completed" u artifacts wieħed jew aktar. Kull artifact għandu artifactId uniku, name speċifiku għall-iskill, u waħda jew aktar parts (text, data, jew file).

catholic_qa

Staqsi mistoqsija f'lingwa naturali u irċievi risposta twila u bi ċitazzjonijiet. Din hija l-iskill l-aktar kapaċi (u l-aktar intensiva fir-riżorsi) — iddur fuq l-istess mudell li jħaddem magisterium.com.

Input: parti waħda ta' test bil-mistoqsija.

Artifact: name: "catholic_qa_response" jikkontjeni:

• Parti text bir-risposta sħiħa.
• Parti data b'citations (meta ntużaw sorsi).
• Parti data b'related_questions (meta l-mudell jagħti suġġerimenti).

{
  "artifactId": "art_...",
  "name": "catholic_qa_response",
  "parts": [
    { "kind": "text", "text": "The Catholic Church teaches..." },
    { "kind": "data", "data": { "citations": [ /* ... */ ] } },
    { "kind": "data", "data": { "related_questions": [ /* ... */ ] } }
  ]
}

catholic_qa juża varjanta tar-rate-limit aktar stretta mill-iskills l-oħrajn. Ara Referenza API → Limiti tar-Rate.

document_search

Iġbor referenzi ta' dokumenti li jaqblu ma' mistoqsija semantika kontra l-bażi ta' għarfien ta' Magisterium.

Input: parti waħda ta' test bil-mistoqsija.

Artifact: name: "search_results" b'parti data waħda:

{
  "artifactId": "art_...",
  "name": "search_results",
  "parts": [
    {
      "kind": "data",
      "data": {
        "results": [
          { "id": "12345", "url": "https://...", "title": "Lumen Gentium" }
        ]
      }
    }
  ]
}

Uża l-kamp id minn riżultat biex issejjaħ document_fetch għat-test sħiħ.

document_fetch

Iġbor it-test sħiħ u l-metadata ta' dokument bl-ID tiegħu. Din l-iskill taċċetta parti data minflok parti ta' test:

{
  "parts": [{ "kind": "data", "data": { "id": "12345" } }]
}

Jekk min isejjaħ jibgħat parti ta' test, il-handler iwaqa' fuqha u jittrattaha bħala l-ID tad-dokument.

Artifact: name: "document" b'żewġ partijiet:

• Parti text li fiha l-korp tad-dokument.
• Parti data b'{ id, title, author, ref }.

Jekk id-dokument ma jinstabx, l-artifact ikun fih parti text waħda li taqra "Document not found.".

liturgical_readings

Akkwista l-qari tal-Quddiesa Kattolika għal data partikolari. Jaċċetta mistoqsija tad-data f'lingwa naturali — eż. "today", "next Sunday", jew "Easter Sunday 2026".

Input: parti waħda ta' test bil-mistoqsija tad-data.

Artifact: name: "mass_readings" b'parti text waħda li fiha l-qari formattjat. Jekk ma jkunx hemm qari disponibbli għad-data mitluba, il-parti tgħid "No mass readings found.".

saints_of_the_day

Fittex il-qaddisin imfakkra f'data partikolari mill-Martiroloġju Ruman.

Input: parti data b'data assoluta, jew parti ta' test ittrattata bħala mistoqsija tad-data:

{
  "parts": [{ "kind": "data", "data": { "date": "2026-03-19" } }]
}

Artifact: name: "martyrology" b'parti text waħda li fiha l-entrata tal-martiroloġju formattjata. Dati neqsin jagħtu lura "No martyrology data found.".

Il-ħames skills li ġejjin huma tfittxijiet f'direttorju. Kull waħda taċċetta query f'lingwa naturali (bħala parti ta' test jew kamp data.query) flimkien ma' ID kanoniku fakultattiv, u tirritorna profil strutturat ġewwa parti data waħda. Jekk la query u lanqas ID kanoniku ma jiġi pprovdut, it-talba tiġi rrifjutata bi INVALID_PARAMS (-32602).

Meta l-mistoqsija ma tistax tiġi solvuta, l-artifact ikun fih parti data tal-forma { "error": "not_found", "query": "...", "hint"?: "..." } minflok profil. Il-biċċa xogħol innifisha xorta tlesti b'suċċess — not_found huwa riżultat normali ta' tfittxija, mhux żball tal-protokoll.

saint_lookup

Fittex qaddis, beatu, venerabbli, jew qaddej ta' Alla mid-direttorju cd_saints (~12,500 figura).

Input: data.query (eż. "Therese of Lisieux") jew data.saint_id (ċavetta primarja kanonika, eż. "jerome"). Parti ta' test bla aktar tiġi aċċettata bħala query.

{
  "parts": [{ "kind": "data", "data": { "query": "Catherine of Siena" } }]
}

Artifact: name: "saint_profile" b'parti data waħda li fiha l-profil kanoniku — saint_id, primary_name, canonical_status, vocation, image_url, learn_more_url, ħajja u mewt, jum tal-festa, kawża tal-kanonizzazzjoni, patroċinju, ikonografija, bijografija, u (jekk instabu diversi kandidati) array alternates.

person_lookup

Fittex figura tal-kleru Kattoliku (isqof, kardinal, arċisqof, eċċ.) mid-direttorji cd_persons (ħaj, ~3,500) u cd_persons_historical (~2,200). Il-papiet jiġu esposti permezz tal-iskill separat pope_lookup.

Input: data.query (eż. "Cardinal Tagle") jew data.person_id (ċavetta primarja kanonika). Parti ta' test bla aktar tiġi aċċettata bħala query.

{
  "parts": [{ "kind": "data", "data": { "query": "Cardinal Tagle" } }]
}

Artifact: name: "person_profile" b'parti data waħda li fiha l-profil kanoniku — person_id, source_table, primary_name, current_position, image_url, coat_of_arms_url, dati ta' ordinazzjoni u konsagrazzjoni, elevazzjoni għal kardinal, lineja episkopali, edukazzjoni, motto, u kwalunkwe alternates.

Jekk il-mistoqsija tirriżolvi biss għal papa, ir-risposta hija { "error": "not_found", "hint": "Top match looks like a pope; try get_pope." }.

pope_lookup

Fittex papa mid-direttorju cd_popes (267 figura).

Input: data.query (eż. "Pope Francis", "John Paul II") jew data.pope_id (ċavetta primarja kanonika, eż. "benedict-xvi"). Parti ta' test bla aktar tiġi aċċettata bħala query.

{
  "parts": [{ "kind": "data", "data": { "query": "John Paul II" } }]
}

Artifact: name: "pope_profile" b'parti data waħda li fiha l-profil papali kanoniku — pope_id, primary_name, papal_name, ordinal, pope_title, image_url, coat_of_arms_url, birth_name, origin, pontificate, status tal-beatifikazzjoni u kanonizzazzjoni, u kwalunkwe alternates.

Jekk il-mistoqsija tirriżolvi biss għal membru tal-kleru li mhuwiex papa, ir-risposta hija { "error": "not_found", "hint": "Top match looks like a non-pope clergy member; try get_person." }.

diocese_lookup

Fittex ġurisdizzjoni ekkleżjastika (djoċesi, arċidjoċesi, eparkija, eċċ.) mid-direttorju tad-djoċesijiet (~3,200 ġurisdizzjoni mad-dinja).

Input: data.query (eż. "Archdiocese of Manila") jew data.source_code (ċavetta primarja kanonika, eż. "dmaml"). Parti ta' test bla aktar tiġi aċċettata bħala query.

{
  "parts": [{ "kind": "data", "data": { "query": "Archdiocese of Manila" } }]
}

Artifact: name: "diocese_profile" b'parti data waħda li fiha metadata tad-direttorju (source_code, primary_name, jurisdiction_type, rite, country, region_primary, state, city, metropolitan, depends_on, province, cathedral, patron_saint, area, erected, elevated, official_website, image_url, current_bishop) flimkien ma':

• recent_statistics — sa 5 snin ta' figuri ewlenin (kattoliċi, popolazzjoni totali, perċentwal Kattoliku, qassisin totali, parroċċi, magħmudijiet, seminaristi).
• latest_financials — l-aktar metriċi ewlenin tal-aħħar sena fiskali (dħul totali, spejjeż totali, assi netti, assi totali, surplus/defiċit) meta jkunu disponibbli, bil-munita.
• alternates — meta jaqblu diversi kandidati.

Għal analiżi ta' tendenzi għal diversi snin, uża minflok diocese_statistics_lookup.

diocese_statistics_lookup

Irritorna s-sensiela temporali sħiħa ta' statistika annwali għal djoċesi — il-19-il metrika kollha ttraċkjati f'diocese_statistics.

Input: data.query jew data.source_code (waħda hija meħtieġa), flimkien ma' limiti inklużivi fakultattivi:

{
  "parts": [{
    "kind": "data",
    "data": {
      "source_code": "dmaml",
      "start_year": 2010,
      "end_year": 2024
    }
  }]
}

Artifact: name: "diocese_statistics_time_series" b'parti data waħda li fiha source_code, diocese_name, year_range: { start, end }, u array rows. Kull ringiela ġġorr 19-il metrika għal sena waħda: catholics, total_population, percent_catholic, diocesan_priests, religious_priests, total_priests, catholics_per_priest, permanent_deacons, male_religious, female_religious, parishes, area_km2, churches_or_stations, diocesan_priests_ordained, religious_priests_ordained, seminarians, educational_institutes, charitable_institutes, baptisms.