Matomo LLM Tooling

Gör Matomos rapporterings- och spårnings-API:er tillgängliga för Optimizely Opal-agenter med ett typat SDK och Fastify-verktyg.

matomoanalysllmsdkoptimizelyautomation

Stora språkmodellsagenter börjar bli användbara i vardagens analysarbete – så länge du matar dem med pålitliga verktyg. Matomo LLM Tooling är min brygga mellan Optimizely Opal-agenter och Matomo-stackens rapportering och spårning: ett TypeScript-SDK, ett Fastify-baserat verktygs-API och pragmatiska hjälpare som gör både läs- och skrivflöden säkra att automatisera.

Projektet lever i MatoKit och återanvänder dess connector som kopplar Optimizely Opal till Matomo. Under huven exponerar vi Matomos Reporting- och Tracking-API:er via en Opal-kompatibel yta som gömmer det krångliga (auth, segment-syntax, rate limits) men låter agenten styra analysen.

Varför LLM-verktyg för Matomo?

Matomos API:er är flexibla men pratsamma. Analytiker och growth-team lägger tid på frågesträngar, token-auth och dataset-joiner innan de ens kan ställa en fråga. Samtidigt kan Opal-agenter orkestrera flerstegsexperiment – men de behöver typade primitiv för att undvika skräp in/soppa ut. Matomo LLM Tooling vill:

  • Snabba upp discovery – leverera maskinläsbar verktygsmetadata så att Opal-agenter vet vilka åtgärder som finns och vilka parametrar de accepterar.
  • Garantera kontrakt – kompilera ett typat SDK med genererade gränssnitt för Matomo-endpoints så att agenten slipper gissa i prompten.
  • Balansera read vs write – samla rapportfrågor och spårningspayloads i ett enda toolkit så agenten kan hämta baslinjer, föreslå experiment och trycka ut mätningar utan kontextbyte.
  • Hålla styrning intakt – centralisera auth, caching och segmentregler istället för att sprida tokens i prompts.

Vad som skeppas först

Fokus just nu är på tunna lager som snabbt kan stoppas in i automationsflöden:

  1. Typat TypeScript-SDK – wrapper Matomos Reporting- och Tracking-endpoints med tydliga input/output-strukturer, runtime-validering via Zod och smidiga hjälpare för segment, datumintervall och målmetadata.
  2. Fastify-”tools”-tjänst – hostar HTTP-endpoints som mappar 1:1 mot vanliga analysflöden (t.ex. report.getVisitsSummary, events.pushCustomEvent). Varje endpoint publicerar Opal-discovery-metadata så agenter kan självanmäla sig utan manuell kabeldragning.
  3. Connector-lim – bygger på MatoKits Optimizely Opal-connector för att autentisera agenter, upprätthålla scopes och skicka svar tillbaka till Opal. Den behåller human-in-the-loop-godkännandet som teamen redan litar på.
  4. Hjälpbibliotek för robusthet – delade moduler för exponentiell backoff, memoisering av tunga rapporter, konsekvent tidszonslogik och mjuk degradering när Matomo stryper.

Exempel på agentflöde

Ett typiskt Opal-flöde kan se ut så här:

  1. Anropa verktyget insights.getKpis för att hämta en 30-dagars baslinje för konverteringsgrad och avhopp i kassan.
  2. Använd SDK:ets segmenteringshjälpare för att jämföra kohorter baserat på samtycke eller geografi utan att läcka tokens i prompten.
  3. Skissa ett experimentunderlag och kör sedan tracking.queueEvent för att skicka ett Matomo-mål för QA eller registrera ett nytt trattsteg.
  4. Logga förändringar och strukturerade metriker tillbaka i Opal för granskning.

Varje verktygssvar innehåller ursprungsmetadata, vilket låter människor granska agentens steg innan något går live.

Roadmap och inbjudan

På kort sikt prioriterar jag spårningsdelen – batchade payloads, offline-köer och rikare validering för e-handels-händelser. På längre sikt vill jag lägga till experimentmallar som mappar Opal-hypoteser till Matomo Content Tracking samt förstklassigt stöd för integritetsbevarande metriker.

Om du lutar dig mot Matomo och testar Opal eller andra LLM-agenter får du gärna höra av dig. Mejla mig eller öppna ett issue i MatoKit-repot så jämför vi integrationsnoteringar.

Kom igång

Projektet är fortfarande privat medan jag stabiliserar SDK-ytan. Vill du labba redan nu?

  1. Be om åtkomst till MatoKit-repot.
  2. Hämta paketet matomo-llm-tooling och kör pnpm install && pnpm dev för att starta Fastify-verktygsservern lokalt.
  3. Konfigurera Opal med det upptäcktsmanifest som servern exponerar så agenten ser de nya verktygen.
  4. Peka servern mot din Matomo-instans med servicetokens som hålls utanför promptkontexten.

Kombinationen låter LLM-agenter ställa bättre analytikfrågor, föreslå modigare experiment och trycka ut rena spårningsuppdateringar utan att rucka på integritet eller regelefterlevnad.