UA Copilot

A metadata-aware agent for performance marketers. It runs the user-acquisition loop — decide → create → test → scale — and checks where every number came from before it recommends spending a dollar, by grounding each decision in DataHub lineage.

Built for the DataHub Agent Hackathon 2026 (track: Agents that do real work).

---

The idea

Performance marketing collapses to a few ratios, and the worst mistakes come from acting on a metric whose upstream pipeline silently broke. UA Copilot makes data freshness a hard gate on every spend decision:

scale  ⇔  predicted_ROAS ≥ target_ROAS   ∧   fresh(lineage)

A campaign can look profitable and still be blocked if the table its numbers came from is stale — that is the whole point of putting DataHub in the loop.

Architecture — three MCP layers, one agent

                 ┌─────────────────────────────────────────────┐
   agent ───────►│  DataHub MCP   →  reads schema + lineage,    │  the trust layer
   (Claude, etc.)│                   derives freshness          │
                 ├─────────────────────────────────────────────┤
                 │  Marketing MCP →  ROAS / CPA / LTV / pacing / │  the toolbox
                 │  (this repo)      the freshness-gated rule    │  (ua_copilot.mcp_server)
                 ├─────────────────────────────────────────────┤
                 │  Ad-platform MCP + API → Meta / Google Ads    │  the channels (prod)
                 │                          (act, not just advise)│
                 └─────────────────────────────────────────────┘

This repo ships the Marketing MCP server, the decision engine, a DataHub adapter, and a runnable demo on sample data. The ad-platform action layer is a production concern (see Disclosure) and is out of scope here — the demo stops at a recommendation.

Quickstart

git clone https://github.com/shiam2018/ua-copilot
cd ua-copilot
python3 -m venv .venv && source .venv/bin/activate
pip install -e .            # installs the `mcp` dependency; the demo itself needs no extras

# 1) run the end-to-end decision loop on sample data
PYTHONPATH=. python examples/run_demo.py

Expected output: a recommendation per campaign (SCALE / HOLD), then the same run with a stale cohort-LTV upstream where every scale is BLOCKED — the trust gate in action.

The Marketing MCP server

python -m ua_copilot.mcp_server      # stdio MCP server: ua-copilot-marketing

Tools exposed to any MCP client: roas, cpa, ltv_projection, pacing, lineage_fresh, scale_decision. Point Claude (or any MCP-capable agent) at this command alongside your DataHub MCP server, and it can reason across both.

Running against a real DataHub (the trust layer)

This is a real DataHub integration, not a mock — see datahub/README.md.

• The agent talks to the official DataHub MCP server (mcp-server-datahub, tools get_lineage / get_entities / search) alongside our marketing MCP — wired in mcp/datahub-agent.mcp.json.
• The decision engine reads the same lineage + freshness programmatically via the DataHub Python SDK: LineageStore.from_datahub(server, token, urns) in ua_copilot/datahub.py (freshness = DataHub's Operation lastUpdatedTimestamp; provenance = the UpstreamLineage aspect).

pip install -e '.[datahub]'
datahub docker quickstart                       # local DataHub
python datahub/emit_sample_metadata.py          # seed datasets + lineage + freshness
DATAHUB_GMS_URL=http://localhost:8080 python examples/run_demo.py   # reads it LIVE

Without a DataHub instance the demo falls back to data/lineage.json, so it always runs.

• Ad platforms: the agent emits recommendations; a production panel applies them via the Meta / Google Ads APIs, behind explicit confirmation (see Disclosure).

Tests

pip install -e . pytest && PYTHONPATH=. pytest -q — the freshness-gated scale rule is unit-tested; CI (.github/workflows/ci.yml) runs the tests + the end-to-end demo on every push.

Repo layout

ua_copilot/decision.py     pure decision math (ROAS, LTV projection, pacing, the gate)
ua_copilot/datahub.py      DataHub adapter — freshness/lineage (trust layer)
ua_copilot/mcp_server.py   Marketing MCP server exposing the tools
ua_copilot/agent.py        orchestrator: loop → project → gate → recommend
data/                      sample warehouse + lineage manifest
examples/run_demo.py       end-to-end demo (no external services)

Disclosure & provenance

• Newly created during the Submission Period. This repository — the DataHub-grounded agent, the Marketing MCP server, the decision engine, and the demo — was written from scratch during the hackathon submission window (July 6 – Aug 10, 2026). Only standard libraries and the MCP SDK are used.
• Pre-existing systems (disclosed, not included). In production, the action layer connects to a separate, pre-existing private Meta Ads buying panel (official Marketing API, safety-first: read-only by default, everything created paused, every money move confirmed and logged). That system is not part of this submission and none of its code is included here; this repo implements the new DataHub-grounding and MCP-tool layer that the hackathon adds on top.

License

Licensed under the Apache License 2.0.