logly/mureo

Per-platform analytics module surface for external-integration platforms (#120)

External-integration platforms — official MCPs and third-party plugins alike — now have an opt-in path to mureo's deep analytics on the same terms as the built-in google_ads / meta_ads adapters. Workflow skills (daily-check, rescue, …) consult a new registry and either run the platform's analytics module or honestly report analytics_not_available_for_<platform>. Auto-deriving heuristics from tool schemas is explicitly rejected — it would fabricate plausible-but-wrong analysis and violate mureo's trustworthiness principle.

New public surface in mureo.analytics

• Protocol — AnalyticsModule (runtime_checkable, opt-in) with four methods: detect_anomalies, diagnose_performance, audit_creative, analyze_budget_efficiency. Modules advertise their actually-supported subset via capabilities(); un-advertised methods raise NotImplementedError. Discovery validates structurally and detects un-overridden Protocol stubs by qualified name.
• Capability enum — AnalyticsCapability (DETECT_ANOMALIES, DIAGNOSE_PERFORMANCE, AUDIT_CREATIVE, ANALYZE_BUDGET_EFFICIENCY).
• Frozen-dataclass models — Anomaly, AnomalySeverity, PerformanceDiagnosis (with optional per_campaign_metrics for DEEP scope), PerformanceScope, CreativeAudit (with findings + per_campaign_summary), CreativeFinding (with campaign_id), BudgetEfficiency.
• Registry — entry-point group mureo.analytics, independent of mureo.providers / mureo.skills. Plugin packages register one class via [project.entry-points."mureo.analytics"]. Built-in adapters auto-register; broken plugins are skipped with AnalyticsModuleWarning and never crash the MCP server.
• MCP tool — mureo_analytics_modules_list returns the registered platforms + advertised capabilities + source distribution so skills can branch dynamically.
• TypedDicts — GoogleLivePerformanceRow, GoogleByodPerformanceRow, GoogleMetricsDict, GooglePerformanceRow, MetaLivePerformanceRow, MetaByodPerformanceRow, MetaActionEntry, MetaPerformanceRow, GoogleAdRow, MetaAdRow — re-exported for plugin-side typing. All total=False; field-set contract documented in docs/ABI-stability.md §4a.

Built-in adapters wired against live + BYOD clients

• google_ads and meta_ads advertise all four capabilities.
• detect_anomalies runs per-campaign fan-out — single-campaign anomalies are no longer masked by offsetting movements at the aggregate.
• diagnose_performance returns aggregate metrics by default and per-campaign drilldown (sorted by spend descending, one finding per campaign with spend / CV / CPA) at PerformanceScope.DEEP.
• audit_creative checks RSA / RDA / Meta ad shape against Google's Ad-Strength thresholds and Meta's creative requirements, stamps campaign_id on every finding, and exposes a sorted CreativeAudit.per_campaign_summary.
• analyze_budget_efficiency normalises conversions/cost across campaigns and emits a concrete reallocation suggestion when the spread is wide.
• Lazy auth + BYOD routing; missing credentials in live mode produce sentinel responses (empty anomaly tuple, sentinel PerformanceDiagnosis headline). Tolerates both live row shape and BYOD flat shape — regression tests pin both.

Skill integration

daily-check, rescue, _mureo-shared updated to consult mureo_analytics_modules_list before running deep diagnostics on any external-integration platform.

Docs

• docs/plugin-authoring.md §14 "Shipping analytics with your plugin"
• docs/ABI-stability.md §4a (Protocol contract) + §6 (entry-point group mureo.analytics) + TypedDict field-set rules

PRs in this release

• #137 — Protocol + registry + skill integration + docs
• #138 — Live client wiring + BYOD shape fix
• #139 — Per-campaign fan-out + audit_creative + analyze_budget_efficiency
• #140 — Per-campaign drilldown for audit_creative
• #141 — DEEP scope drilldown for diagnose_performance + TypedDicts
• #142 — Release commit

Closes #120.