mixpilot 0.1.0__py3-none-any.whl

mixpilot/__init__.py

@@ -0,0 +1,18 @@
+"""MixPilot: an agentic harness for marketing measurement.
+
+A small, real agent runtime whose action space is the marketing-science toolkit --
+adstock, saturation, attribution, budget allocation, and data-quality auditing --
+with structured tool results, an approval gate, and an eval suite that scores the
+agent's method-selection judgment.
+"""
+
+from .agent.loop import Agent, SYSTEM_PROMPT
+from .tools.registry import Registry, BUILTIN_TOOLS
+from .tools.base import Tool, ToolResult
+from .safety.approval import ApprovalGate, Policy
+
+__version__ = "0.1.0"
+__all__ = [
+    "Agent", "SYSTEM_PROMPT", "Registry", "BUILTIN_TOOLS",
+    "Tool", "ToolResult", "ApprovalGate", "Policy",
+]

mixpilot/agent/__init__.py

@@ -0,0 +1,3 @@
+from .loop import Agent, SYSTEM_PROMPT, RunResult
+from .client import AnthropicClient
+__all__ = ["Agent", "SYSTEM_PROMPT", "RunResult", "AnthropicClient"]

mixpilot/agent/client.py

@@ -0,0 +1,43 @@
+"""Thin Anthropic adapter.
+
+Normalises the Messages API into the dict shape the loop expects:
+create(...) -> {"content": [ {type, ...}, ... ]}
+
+Kept behind an interface so tests/evals can inject a scripted client with the same
+.create() signature and never touch the network.
+"""
+
+from __future__ import annotations
+
+import os
+
+
+class AnthropicClient:
+    def __init__(self, api_key: str | None = None, max_tokens: int = 1500):
+        try:
+            import anthropic
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError(
+                "Install the anthropic SDK: pip install anthropic"
+            ) from exc
+        self._client = anthropic.Anthropic(
+            api_key=api_key or os.environ.get("ANTHROPIC_API_KEY")
+        )
+        self.max_tokens = max_tokens
+
+    def create(self, model, system, tools, messages):
+        resp = self._client.messages.create(
+            model=model,
+            max_tokens=self.max_tokens,
+            system=system,
+            tools=tools,
+            messages=messages,
+        )
+        content = []
+        for block in resp.content:
+            if block.type == "text":
+                content.append({"type": "text", "text": block.text})
+            elif block.type == "tool_use":
+                content.append({"type": "tool_use", "id": block.id,
+                                "name": block.name, "input": block.input})
+        return {"content": content}

mixpilot/agent/groq_client.py

@@ -0,0 +1,118 @@
+"""Groq adapter for the MixPilot agent loop.
+
+Groq's API follows OpenAI conventions, which differ from Anthropic's tool-use shape.
+Rather than teach the loop two dialects, we normalise at the edge: this adapter
+exposes the same .create(model, system, tools, messages) interface the loop uses,
+translating Anthropic-style tools/messages INTO OpenAI/Groq format on the way in,
+and translating Groq's response BACK into Anthropic-style content blocks on the way
+out. The loop never knows which provider it is talking to.
+
+The three translation functions are module-level and pure, so they are unit-tested
+without any network call (see tests/test_groq_translation.py).
+"""
+
+from __future__ import annotations
+
+import json
+import os
+from typing import Any
+
+
+def to_openai_tools(anthropic_tools: list[dict]) -> list[dict]:
+    """Anthropic {name, description, input_schema} -> OpenAI function tools."""
+    return [
+        {
+            "type": "function",
+            "function": {
+                "name": t["name"],
+                "description": t.get("description", ""),
+                "parameters": t.get("input_schema", {"type": "object", "properties": {}}),
+            },
+        }
+        for t in anthropic_tools
+    ]
+
+
+def to_openai_messages(system: str, messages: list[dict]) -> list[dict]:
+    """Translate the loop's Anthropic-shaped history into OpenAI chat messages."""
+    out: list[dict] = [{"role": "system", "content": system}]
+    for msg in messages:
+        role, content = msg["role"], msg["content"]
+
+        if isinstance(content, str):
+            out.append({"role": role, "content": content})
+            continue
+
+        if role == "assistant":
+            text_parts, tool_calls = [], []
+            for block in content:
+                if block.get("type") == "text":
+                    text_parts.append(block["text"])
+                elif block.get("type") == "tool_use":
+                    tool_calls.append({
+                        "id": block["id"],
+                        "type": "function",
+                        "function": {
+                            "name": block["name"],
+                            "arguments": json.dumps(block.get("input", {})),
+                        },
+                    })
+            am: dict[str, Any] = {"role": "assistant",
+                                   "content": " ".join(text_parts) or None}
+            if tool_calls:
+                am["tool_calls"] = tool_calls
+            out.append(am)
+
+        else:  # user turn carrying tool_result blocks
+            for block in content:
+                if block.get("type") == "tool_result":
+                    out.append({
+                        "role": "tool",
+                        "tool_call_id": block["tool_use_id"],
+                        "content": block["content"],
+                    })
+                else:
+                    out.append({"role": "user", "content": block.get("text", "")})
+    return out
+
+
+def from_groq_response(message) -> dict:
+    """Groq/OpenAI response message -> Anthropic-style {"content": [...blocks]}."""
+    content: list[dict] = []
+    text = getattr(message, "content", None)
+    if text:
+        content.append({"type": "text", "text": text})
+    for tc in getattr(message, "tool_calls", None) or []:
+        try:
+            args = json.loads(tc.function.arguments or "{}")
+        except json.JSONDecodeError:
+            args = {}
+        content.append({"type": "tool_use", "id": tc.id,
+                        "name": tc.function.name, "input": args})
+    if not content:
+        content.append({"type": "text", "text": ""})
+    return {"content": content}
+
+
+class GroqClient:
+    """Drop-in replacement for AnthropicClient, backed by Groq."""
+
+    def __init__(self, api_key: str | None = None,
+                 model: str = "llama-3.3-70b-versatile", max_tokens: int = 1500):
+        try:
+            from groq import Groq
+        except ImportError as exc:  # pragma: no cover
+            raise ImportError("Install the Groq SDK: pip install groq") from exc
+        self._client = Groq(api_key=api_key or os.environ.get("GROQ_API_KEY"))
+        self.default_model = model
+        self.max_tokens = max_tokens
+
+    def create(self, model, system, tools, messages):
+        resp = self._client.chat.completions.create(
+            model=model or self.default_model,
+            max_tokens=self.max_tokens,
+            messages=to_openai_messages(system, messages),
+            tools=to_openai_tools(tools),
+            tool_choice="auto",
+        )
+        return from_groq_response(resp.choices[0].message)

mixpilot/agent/loop.py

@@ -0,0 +1,110 @@
+"""The agent loop: a control system, not a while-tool-calls toy.
+
+It owns the marketing-analyst system prompt, exposes the registry's tools to the
+model, executes tool calls through the registry pipeline, feeds structured results
+back as observations, and enforces stop conditions: a max-turn budget and a loop
+detector that halts when the model repeats the same tool call with no progress.
+
+The Anthropic client is injected, so the loop is testable without a live model
+(see tests/ and evals/ which drive it with a scripted client).
+"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import dataclass, field
+
+from ..tools.registry import Registry
+
+SYSTEM_PROMPT = """You are a senior marketing-measurement analyst running inside a \
+tool-using agent. Your job is to turn raw marketing data and messy business \
+questions into defensible measurement conclusions.
+
+Operating principles:
+- ALWAYS audit data quality before modelling. If high-severity issues exist, say so \
+and stop rather than producing a confident-but-wrong answer.
+- Choose the analysis that matches the DATA SHAPE, not the fanciest one. Do not run \
+Markov attribution on single-touch paths. Do not trust a saturation curve with low R2.
+- Adstock before saturation; saturation before budget allocation.
+- State assumptions and the limits of each conclusion. Extrapolating beyond observed \
+spend ranges is unreliable; say so.
+- When you have reached a defensible conclusion, stop calling tools and give a final \
+answer with the business implication, not just the numbers.
+
+The judgment layer -- knowing which question to ask and which method the data can \
+actually support -- is the point. Tools are how you act on that judgment."""
+
+
+@dataclass
+class Turn:
+    role: str
+    content: object
+
+
+@dataclass
+class RunResult:
+    final_text: str
+    turns: list[Turn] = field(default_factory=list)
+    tool_calls: list[dict] = field(default_factory=list)
+    stop_reason: str = ""
+
+
+class Agent:
+    def __init__(self, client, registry: Registry | None = None,
+                 model: str = "claude-sonnet-4-6", max_turns: int = 12):
+        self.client = client
+        self.registry = registry or Registry()
+        self.model = model
+        self.max_turns = max_turns
+
+    def run(self, goal: str) -> RunResult:
+        messages = [{"role": "user", "content": goal}]
+        out = RunResult(final_text="", stop_reason="")
+        recent_signatures: list[str] = []
+
+        for _ in range(self.max_turns):
+            resp = self.client.create(
+                model=self.model,
+                system=SYSTEM_PROMPT,
+                tools=self.registry.schemas(),
+                messages=messages,
+            )
+            messages.append({"role": "assistant", "content": resp["content"]})
+            out.turns.append(Turn("assistant", resp["content"]))
+
+            tool_uses = [b for b in resp["content"] if b.get("type") == "tool_use"]
+            text = " ".join(b["text"] for b in resp["content"]
+                            if b.get("type") == "text")
+
+            if not tool_uses:
+                out.final_text = text.strip()
+                out.stop_reason = "final_answer"
+                return out
+
+            # Loop detection: identical tool call signature 3x in a row -> stop.
+            results = []
+            for tu in tool_uses:
+                sig = tu["name"] + json.dumps(tu.get("input", {}), sort_keys=True)
+                recent_signatures.append(sig)
+                if recent_signatures[-3:].count(sig) >= 3:
+                    out.final_text = (text or "").strip()
+                    out.stop_reason = "loop_detected"
+                    return out
+
+                res = self.registry.call(tu["name"], **tu.get("input", {}))
+                out.tool_calls.append({"name": tu["name"], "input": tu.get("input", {}),
+                                        "success": res.success})
+                # The observation handed back to the model is the structured result.
+                payload = res.model_dump(exclude_none=True)
+                results.append({
+                    "type": "tool_result",
+                    "tool_use_id": tu["id"],
+                    "content": json.dumps(payload),
+                    "is_error": not res.success,
+                })
+            messages.append({"role": "user", "content": results})
+            out.turns.append(Turn("user", results))
+
+        out.stop_reason = "max_turns"
+        out.final_text = "Reached max turns without a final answer."
+        return out

mixpilot/safety/__init__.py

@@ -0,0 +1,2 @@
+from .approval import ApprovalGate, Policy, Decision
+__all__ = ["ApprovalGate", "Policy", "Decision"]

mixpilot/safety/approval.py

@@ -0,0 +1,41 @@
+"""Approval policy: safety enforced in code, not in prose.
+
+Mutating actions (writing a report, exporting a file) must clear a policy gate that
+lives outside the model. The model cannot talk its way past it.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+from enum import Enum
+
+
+class Policy(str, Enum):
+    ON_REQUEST = "on_request"  # ask a human callback before any mutating action
+    AUTO = "auto"              # allow mutating actions automatically
+    NEVER = "never"            # block all mutating actions
+
+
+@dataclass
+class Decision:
+    approved: bool
+    reason: str = ""
+
+
+class ApprovalGate:
+    def __init__(self, policy: Policy = Policy.ON_REQUEST, ask=None):
+        self.policy = policy
+        self.ask = ask  # optional callable(name, args) -> bool
+
+    def check(self, name: str, args: dict) -> Decision:
+        if self.policy is Policy.AUTO:
+            return Decision(True, "auto policy")
+        if self.policy is Policy.NEVER:
+            return Decision(False, "never policy blocks mutating actions")
+        # ON_REQUEST
+        if self.ask is None:
+            return Decision(False, "no approval callback configured")
+        try:
+            return Decision(bool(self.ask(name, args)), "human callback")
+        except Exception as exc:  # noqa: BLE001
+            return Decision(False, f"approval callback error: {exc}")

mixpilot/tools/__init__.py

@@ -0,0 +1,3 @@
+from .registry import Registry, BUILTIN_TOOLS
+from .base import Tool, ToolResult
+__all__ = ["Registry", "BUILTIN_TOOLS", "Tool", "ToolResult"]

mixpilot/tools/adstock.py

@@ -0,0 +1,78 @@
+"""Adstock: the carryover transform at the heart of MMM.
+
+Geometric (exponential) adstock with an optional max-lag window:
+
+    a[t] = sum_{l=0..L} w[l] * x[t-l],   w[l] = decay**l  (normalised to sum 1)
+
+Carryover models the fact that media exposure today keeps driving response for
+several periods. `decay` in [0, 1) is the fraction of effect retained each period.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Tool, ToolResult
+
+
+def adstock_transform(
+    spend: list[float],
+    decay: float = 0.5,
+    max_lag: int = 8,
+    normalise: bool = True,
+) -> ToolResult:
+    x = np.asarray(spend, dtype=float)
+    if x.ndim != 1 or x.size == 0:
+        return ToolResult.fail(
+            "spend must be a non-empty 1-D list of period spend values.",
+            recovery_hint="Pass spend as a flat list, e.g. [100, 120, 0, 90].",
+        )
+    if not 0.0 <= decay < 1.0:
+        return ToolResult.fail(
+            f"decay={decay} is out of range; must be in [0, 1).",
+            recovery_hint="Typical TV decay ~0.6-0.8, digital ~0.1-0.4. Use a value < 1.",
+        )
+
+    weights = decay ** np.arange(max_lag + 1)
+    if normalise:
+        weights = weights / weights.sum()
+
+    out = np.convolve(x, weights)[: x.size]
+    half_life = np.log(0.5) / np.log(decay) if decay > 0 else 0.0
+
+    return ToolResult.ok(
+        output=f"Adstocked series (first 5): {np.round(out[:5], 2).tolist()}",
+        summary=(
+            f"Applied geometric adstock (decay={decay}, max_lag={max_lag}). "
+            f"Effective half-life ~{half_life:.1f} periods."
+        ),
+        artifacts={
+            "adstocked": np.round(out, 4).tolist(),
+            "weights": np.round(weights, 4).tolist(),
+            "half_life_periods": round(float(half_life), 2),
+        },
+        next_actions=[
+            "Fit a saturation curve on the adstocked series before regressing on sales.",
+        ],
+    )
+
+
+TOOL = Tool(
+    name="adstock_transform",
+    description=(
+        "Apply geometric adstock (media carryover) to a spend series. Use this "
+        "BEFORE saturation and before regressing media on sales. Returns the "
+        "adstocked series and the implied half-life."
+    ),
+    parameters={
+        "spend": {"type": "array", "items": {"type": "number"},
+                   "description": "Per-period spend for one channel."},
+        "decay": {"type": "number", "description": "Carryover rate in [0,1). "
+                   "Higher = longer carryover.", "optional": True},
+        "max_lag": {"type": "integer", "description": "Max carryover window in "
+                     "periods.", "optional": True},
+        "normalise": {"type": "boolean", "description": "Normalise weights to sum "
+                       "to 1.", "optional": True},
+    },
+    fn=adstock_transform,
+)

mixpilot/tools/attribution.py

@@ -0,0 +1,157 @@
+"""Multi-touch attribution.
+
+Three models, in increasing order of sophistication and data demands:
+
+- last_touch:  100% credit to the final channel before conversion. Cheap, biased,
+               but all you can do with last-click data.
+- linear:      equal credit across touchpoints.
+- markov:      data-driven credit via the *removal effect* of each channel in an
+               absorbing Markov chain. Credit(c) is proportional to the drop in
+               total conversion probability when channel c is removed from the graph.
+
+The Markov model is the defensible one when you have full multi-touch path data; it
+captures assist value that last-touch throws away. It needs real path variety to be
+stable -- the eval suite checks exactly that.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Tool, ToolResult
+
+START, CONV, NULL = "(start)", "(conversion)", "(null)"
+
+
+def _build_chain(paths, channels):
+    """Build transition + absorption counts for the absorbing Markov chain."""
+    states = [START] + channels
+    idx = {s: i for i, s in enumerate(states)}
+    n = len(states)
+    trans = np.zeros((n, n))
+    to_conv = np.zeros(n)
+    to_null = np.zeros(n)
+    for path, converted in paths:
+        seq = [START] + [c for c in path if c in idx]
+        for a, b in zip(seq[:-1], seq[1:]):
+            trans[idx[a], idx[b]] += 1
+        last = idx[seq[-1]]
+        (to_conv if converted else to_null)[last] += 1
+    return states, idx, trans, to_conv, to_null
+
+
+def _conv_prob(states, idx, trans, to_conv, to_null, removed=None):
+    """Absorption probability into (conversion) from (start).
+
+    To remove a channel (removal effect), every transition INTO that channel is
+    rerouted to the null absorbing state -- i.e. any journey that relied on the
+    channel is counted as a non-conversion. This is the standard removal-effect
+    definition (not path compression).
+    """
+    n = len(states)
+    trans = trans.copy()
+    to_conv = to_conv.copy()
+    to_null = to_null.copy()
+    if removed is not None and removed in idx:
+        ri = idx[removed]
+        to_null += trans[:, ri]   # inbound mass becomes a non-conversion
+        trans[:, ri] = 0          # channel is now unreachable
+        trans[ri, :] = 0
+        to_conv[ri] = 0
+        to_null[ri] = 0
+    row = trans.sum(1) + to_conv + to_null
+    row[row == 0] = 1.0
+    Q = trans / row[:, None]
+    r_conv = to_conv / row
+    try:
+        N = np.linalg.inv(np.eye(n) - Q)
+    except np.linalg.LinAlgError:
+        return 0.0
+    return float((N @ r_conv)[idx[START]])
+
+
+def run_attribution_model(
+    paths: list[dict],
+    model: str = "markov",
+) -> ToolResult:
+    if not paths:
+        return ToolResult.fail("paths is empty.", recovery_hint="Provide conversion paths.")
+    norm = []
+    for p in paths:
+        seq = p.get("path") or p.get("channels")
+        if not seq:
+            return ToolResult.fail(
+                "Each path needs a 'path' list of channels.",
+                recovery_hint="Format: {'path': ['Search','Social'], 'converted': true}.",
+            )
+        norm.append((list(seq), bool(p.get("converted", False))))
+
+    channels = sorted({c for seq, _ in norm for c in seq})
+    n_conv = sum(1 for _, c in norm if c)
+
+    if model == "last_touch":
+        credit = {c: 0.0 for c in channels}
+        for seq, conv in norm:
+            if conv:
+                credit[seq[-1]] += 1
+    elif model == "linear":
+        credit = {c: 0.0 for c in channels}
+        for seq, conv in norm:
+            if conv and seq:
+                for c in seq:
+                    credit[c] += 1 / len(seq)
+    elif model == "markov":
+        states, idx, trans, to_conv, to_null = _build_chain(norm, channels)
+        base = _conv_prob(states, idx, trans, to_conv, to_null)
+        if base <= 0:
+            return ToolResult.fail(
+                "Base conversion probability is zero; Markov attribution is undefined.",
+                recovery_hint="No converting paths, or paths too sparse. Use last_touch.",
+            )
+        removal = {}
+        for c in channels:
+            dropped = _conv_prob(states, idx, trans, to_conv, to_null, removed=c)
+            removal[c] = max(base - dropped, 0.0)
+        total = sum(removal.values()) or 1.0
+        credit = {c: removal[c] / total * n_conv for c in channels}
+    else:
+        return ToolResult.fail(
+            f"Unknown model '{model}'.",
+            recovery_hint="Choose one of: last_touch, linear, markov.",
+        )
+
+    total = sum(credit.values()) or 1.0
+    share = {c: round(credit[c] / total, 4) for c in credit}
+    ranked = sorted(share.items(), key=lambda kv: -kv[1])
+
+    return ToolResult.ok(
+        output="Credit share: " + ", ".join(f"{c}={s:.1%}" for c, s in ranked),
+        summary=(
+            f"{model} attribution over {len(norm)} paths ({n_conv} conversions). "
+            f"Top channel: {ranked[0][0]} ({ranked[0][1]:.1%})."
+        ),
+        artifacts={"model": model, "credit": {c: round(v, 3) for c, v in credit.items()},
+                    "share": share},
+        next_actions=[
+            "If using markov, sanity-check against last_touch to quantify assist value.",
+        ],
+    )
+
+
+TOOL = Tool(
+    name="run_attribution_model",
+    description=(
+        "Assign conversion credit across channels from multi-touch path data. "
+        "model='markov' uses removal effect (best with rich path data); "
+        "'last_touch' and 'linear' are heuristics for thin data. Pick the model that "
+        "matches the data shape -- do not run markov on single-touch paths."
+    ),
+    parameters={
+        "paths": {"type": "array",
+                   "description": "List of {'path': [channels...], 'converted': bool}.",
+                   "items": {"type": "object"}},
+        "model": {"type": "string", "enum": ["markov", "last_touch", "linear"],
+                   "description": "Attribution model.", "optional": True},
+    },
+    fn=run_attribution_model,
+)

mixpilot/tools/base.py

@@ -0,0 +1,107 @@
+"""Tool contract for MixPilot.
+
+The central lesson borrowed from harness engineering: a tool result is not a log
+line, it is the next observation in the agent's reasoning loop. Its quality
+directly determines the quality of the next decision. So every tool -- success or
+failure -- returns a structured ToolResult with a plain-language summary, the safe
+next actions, and a recovery hint.
+"""
+
+from __future__ import annotations
+
+from typing import Any, Callable
+
+from pydantic import BaseModel, Field
+
+
+class ToolResult(BaseModel):
+    """The observation an agent receives after a tool runs."""
+
+    success: bool
+    status: str = "success"
+    output: str = ""
+    error: str | None = None
+    # The four fields that turn a result into a usable observation:
+    summary: str | None = None
+    artifacts: dict[str, Any] = Field(default_factory=dict)
+    next_actions: list[str] = Field(default_factory=list)
+    recovery_hint: str | None = None
+
+    @classmethod
+    def ok(
+        cls,
+        output: str,
+        summary: str | None = None,
+        artifacts: dict[str, Any] | None = None,
+        next_actions: list[str] | None = None,
+    ) -> "ToolResult":
+        return cls(
+            success=True,
+            status="success",
+            output=output,
+            summary=summary,
+            artifacts=artifacts or {},
+            next_actions=next_actions or [],
+        )
+
+    @classmethod
+    def fail(
+        cls,
+        error: str,
+        recovery_hint: str | None = None,
+        next_actions: list[str] | None = None,
+    ) -> "ToolResult":
+        return cls(
+            success=False,
+            status="error",
+            error=error,
+            recovery_hint=recovery_hint
+            or "Inspect the inputs, correct the tool arguments, and retry only if the "
+            "analysis still makes sense for this data shape.",
+            next_actions=next_actions
+            or ["Re-check the input data and column assumptions before retrying."],
+        )
+
+
+class Tool(BaseModel):
+    """A typed, validated marketing-analysis action the agent can take."""
+
+    name: str
+    description: str
+    # JSON-schema-style parameter spec exposed to the model.
+    parameters: dict[str, Any]
+    # Whether running this tool mutates state (writes a file, etc).
+    mutating: bool = False
+    fn: Callable[..., ToolResult]
+
+    model_config = {"arbitrary_types_allowed": True}
+
+    def run(self, **kwargs: Any) -> ToolResult:
+        try:
+            return self.fn(**kwargs)
+        except TypeError as exc:
+            return ToolResult.fail(
+                error=f"Bad arguments for {self.name}: {exc}",
+                recovery_hint="Check the tool schema; an argument is missing or the "
+                "wrong type.",
+            )
+        except Exception as exc:  # noqa: BLE001 - surface as a recoverable observation
+            return ToolResult.fail(
+                error=f"{type(exc).__name__} in {self.name}: {exc}",
+            )
+
+    def schema(self) -> dict[str, Any]:
+        """Anthropic tool-use schema."""
+        return {
+            "name": self.name,
+            "description": self.description,
+            "input_schema": {
+                "type": "object",
+                "properties": self.parameters,
+                "required": [
+                    k
+                    for k, v in self.parameters.items()
+                    if not v.get("optional", False)
+                ],
+            },
+        }

mixpilot/tools/budget.py

@@ -0,0 +1,99 @@
+"""Budget allocation under saturation.
+
+Given a Hill curve per channel (beta, alpha, gamma) and a total budget, find the
+spend split that maximises total predicted response, subject to the budget
+constraint and optional per-channel caps. This is where saturation curves pay off:
+the optimiser pushes money toward channels with the most unsaturated marginal
+return and pulls it from channels already on the flat part of their curve.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import minimize
+
+from .base import Tool, ToolResult
+
+
+def _hill(x, beta, alpha, gamma):
+    xa = np.power(np.clip(x, 0, None), alpha)
+    return beta * xa / (xa + np.power(gamma, alpha) + 1e-12)
+
+
+def allocate_budget(
+    curves: dict,
+    total_budget: float,
+    caps: dict | None = None,
+) -> ToolResult:
+    channels = list(curves.keys())
+    if not channels:
+        return ToolResult.fail("curves is empty.",
+                               recovery_hint="Provide fitted Hill params per channel.")
+    if total_budget <= 0:
+        return ToolResult.fail("total_budget must be positive.")
+
+    params = []
+    for c in channels:
+        cv = curves[c]
+        try:
+            params.append((float(cv["beta"]), float(cv["alpha"]), float(cv["gamma"])))
+        except (KeyError, TypeError, ValueError):
+            return ToolResult.fail(
+                f"Channel '{c}' is missing beta/alpha/gamma.",
+                recovery_hint="Run fit_saturation_curve per channel first.",
+            )
+    caps = caps or {}
+    n = len(channels)
+
+    def neg_total(x):
+        return -sum(_hill(x[i], *params[i]) for i in range(n))
+
+    x0 = np.full(n, total_budget / n)
+    bounds = [(0, caps.get(c, total_budget)) for c in channels]
+    cons = {"type": "eq", "fun": lambda x: x.sum() - total_budget}
+    res = minimize(neg_total, x0, method="SLSQP", bounds=bounds, constraints=cons,
+                   options={"maxiter": 500, "ftol": 1e-8})
+    if not res.success:
+        return ToolResult.fail(
+            f"Optimiser failed: {res.message}",
+            recovery_hint="Check caps sum >= total_budget and curve params are sane.",
+        )
+
+    alloc = {c: round(float(v), 2) for c, v in zip(channels, res.x)}
+    predicted = round(float(-res.fun), 2)
+    even = {c: total_budget / n for c in channels}
+    lift = predicted - sum(_hill(even[c], *p) for c, p in zip(channels, params))
+
+    ranked = sorted(alloc.items(), key=lambda kv: -kv[1])
+    return ToolResult.ok(
+        output="Allocation: " + ", ".join(f"{c}={v:,.0f}" for c, v in ranked),
+        summary=(
+            f"Optimal split of {total_budget:,.0f} predicts {predicted:,.0f} response, "
+            f"~{lift:,.0f} above an even split. Top: {ranked[0][0]}."
+        ),
+        artifacts={"allocation": alloc, "predicted_response": predicted,
+                    "lift_vs_even_split": round(float(lift), 2)},
+        next_actions=[
+            "Present allocation with marginal-ROI caveat: extrapolating beyond "
+            "observed spend ranges is unreliable.",
+        ],
+    )
+
+
+TOOL = Tool(
+    name="allocate_budget",
+    description=(
+        "Optimise a media budget split across channels given their fitted Hill "
+        "saturation curves. Maximises total predicted response under the budget "
+        "constraint and optional per-channel caps."
+    ),
+    parameters={
+        "curves": {"type": "object",
+                    "description": "Map channel -> {beta, alpha, gamma} from "
+                    "fit_saturation_curve."},
+        "total_budget": {"type": "number", "description": "Total budget to allocate."},
+        "caps": {"type": "object", "description": "Optional channel -> max spend.",
+                  "optional": True},
+    },
+    fn=allocate_budget,
+)

mixpilot/tools/dataquality.py

@@ -0,0 +1,102 @@
+"""Data-quality audit tailored to marketing-mix data.
+
+Beyond generic null checks, this flags the issues that actually break MMM and
+attribution: zero-variance channels (non-identifiable), multicollinearity between
+channels (unstable coefficients -- the classic MMM trap), negative spend, and date
+gaps. The audit returns structured issues with severity so the agent can decide
+whether the downstream analysis is even trustworthy.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+
+from .base import Tool, ToolResult
+
+
+def audit_data_quality(
+    channels: dict,
+    dates: list | None = None,
+    corr_threshold: float = 0.9,
+) -> ToolResult:
+    if not channels:
+        return ToolResult.fail("channels is empty.",
+                               recovery_hint="Provide channel -> spend series.")
+
+    names = list(channels.keys())
+    lengths = {c: len(v) for c, v in channels.items()}
+    issues = []
+
+    if len(set(lengths.values())) > 1:
+        issues.append({"severity": "high", "type": "length_mismatch",
+                        "detail": f"Channels have unequal lengths: {lengths}."})
+
+    arrs = {}
+    for c, v in channels.items():
+        a = np.asarray(v, dtype=float)
+        arrs[c] = a
+        if np.isnan(a).any():
+            issues.append({"severity": "high", "type": "nulls",
+                            "detail": f"{c} contains {int(np.isnan(a).sum())} nulls."})
+        if (a < 0).any():
+            issues.append({"severity": "high", "type": "negative_spend",
+                            "detail": f"{c} has negative values."})
+        if np.nanstd(a) == 0:
+            issues.append({"severity": "medium", "type": "zero_variance",
+                            "detail": f"{c} is constant; its effect is non-identifiable."})
+
+    # Multicollinearity across channels of equal length.
+    common = [c for c in names if lengths[c] == lengths[names[0]] and np.nanstd(arrs[c]) > 0]
+    if len(common) >= 2:
+        M = np.vstack([arrs[c] for c in common])
+        if not np.isnan(M).any():
+            corr = np.corrcoef(M)
+            for i in range(len(common)):
+                for j in range(i + 1, len(common)):
+                    if abs(corr[i, j]) >= corr_threshold:
+                        issues.append({
+                            "severity": "high", "type": "multicollinearity",
+                            "detail": f"{common[i]} & {common[j]} correlate at "
+                                      f"{corr[i, j]:.2f}; coefficients will be unstable.",
+                        })
+
+    if dates is not None and len(dates) != lengths[names[0]]:
+        issues.append({"severity": "medium", "type": "date_misalignment",
+                        "detail": "dates length does not match channel series length."})
+
+    high = [i for i in issues if i["severity"] == "high"]
+    verdict = ("NOT trustworthy without fixes" if high
+               else "usable with minor caveats" if issues else "clean")
+
+    return ToolResult.ok(
+        output=f"{len(issues)} issue(s) found. Verdict: {verdict}.",
+        summary=(
+            f"Audited {len(names)} channels: {len(high)} high-severity issue(s). "
+            f"Data is {verdict}."
+        ),
+        artifacts={"issues": issues, "verdict": verdict, "n_high": len(high)},
+        next_actions=(
+            ["Resolve high-severity issues before modelling."] if high
+            else ["Proceed to adstock + saturation."]
+        ),
+    )
+
+
+TOOL = Tool(
+    name="audit_data_quality",
+    description=(
+        "Audit marketing-mix data for issues that break MMM/attribution: nulls, "
+        "negative spend, zero-variance (non-identifiable) channels, and "
+        "multicollinearity between channels. Run this FIRST, before any modelling."
+    ),
+    parameters={
+        "channels": {"type": "object",
+                      "description": "Map channel name -> list of per-period spend."},
+        "dates": {"type": "array", "description": "Optional date labels.",
+                   "items": {"type": "string"}, "optional": True},
+        "corr_threshold": {"type": "number",
+                            "description": "Correlation above which to flag "
+                            "multicollinearity.", "optional": True},
+    },
+    fn=audit_data_quality,
+)

mixpilot/tools/registry.py

@@ -0,0 +1,57 @@
+"""Tool registry: the single pipeline every tool call passes through.
+
+Borrowed harness lesson: external/tool output is data, not authority, and every
+action should pass through validation and policy before it runs and before its
+result reaches the model. Here that means: schema lookup, approval check for
+mutating tools, execution, and consistent ToolResult wrapping.
+"""
+
+from __future__ import annotations
+
+from .adstock import TOOL as ADSTOCK
+from .attribution import TOOL as ATTRIBUTION
+from .base import Tool, ToolResult
+from .budget import TOOL as BUDGET
+from .dataquality import TOOL as DATAQUALITY
+from .saturation import TOOL as SATURATION
+
+BUILTIN_TOOLS = [DATAQUALITY, ADSTOCK, SATURATION, ATTRIBUTION, BUDGET]
+
+
+class Registry:
+    def __init__(self, tools: list[Tool] | None = None, approval=None):
+        self._tools: dict[str, Tool] = {}
+        self.approval = approval
+        for t in tools or BUILTIN_TOOLS:
+            self.register(t)
+
+    def register(self, tool: Tool) -> None:
+        if tool.name in self._tools:
+            raise ValueError(f"Duplicate tool name: {tool.name}")
+        self._tools[tool.name] = tool
+
+    def get(self, name: str) -> Tool | None:
+        return self._tools.get(name)
+
+    def schemas(self) -> list[dict]:
+        return [t.schema() for t in self._tools.values()]
+
+    def names(self) -> list[str]:
+        return list(self._tools)
+
+    def call(self, name: str, **kwargs) -> ToolResult:
+        tool = self._tools.get(name)
+        if tool is None:
+            return ToolResult.fail(
+                f"No such tool '{name}'. Available: {', '.join(self._tools)}.",
+                recovery_hint="Call one of the listed tools.",
+            )
+        if tool.mutating and self.approval is not None:
+            decision = self.approval.check(name, kwargs)
+            if not decision.approved:
+                return ToolResult.fail(
+                    f"Action '{name}' blocked by approval policy: {decision.reason}",
+                    recovery_hint="A human must approve this action, or switch to a "
+                    "read-only analysis tool.",
+                )
+        return tool.run(**kwargs)

mixpilot/tools/saturation.py

@@ -0,0 +1,96 @@
+"""Saturation: diminishing returns via the Hill function.
+
+    response(x) = beta * x^alpha / (x^alpha + gamma^alpha)
+
+- alpha (shape) controls the S-curve steepness (alpha>1 gives an S, alpha<=1 is
+  concave-only).
+- gamma (half-saturation) is the spend level at which half the ceiling is reached.
+- beta is the response ceiling.
+
+This is the same family used by Meta's Robyn and most modern MMM stacks. Fitting it
+gives the marginal-return shape you need for budget allocation.
+"""
+
+from __future__ import annotations
+
+import numpy as np
+from scipy.optimize import curve_fit
+
+from .base import Tool, ToolResult
+
+
+def _hill(x, beta, alpha, gamma):
+    xa = np.power(np.clip(x, 0, None), alpha)
+    return beta * xa / (xa + np.power(gamma, alpha) + 1e-12)
+
+
+def fit_saturation_curve(
+    spend: list[float],
+    response: list[float],
+) -> ToolResult:
+    x = np.asarray(spend, dtype=float)
+    y = np.asarray(response, dtype=float)
+    if x.size != y.size or x.size < 4:
+        return ToolResult.fail(
+            "Need spend and response of equal length with at least 4 points.",
+            recovery_hint="Provide paired (spend, response) for the same periods.",
+        )
+    if np.allclose(x.std(), 0):
+        return ToolResult.fail(
+            "Spend has zero variance; a saturation curve cannot be identified.",
+            recovery_hint="This channel has constant spend. You cannot estimate its "
+            "response shape from this data alone.",
+            next_actions=["Flag this channel as non-identifiable and exclude it."],
+        )
+
+    p0 = [y.max() if y.max() > 0 else 1.0, 1.0, np.median(x[x > 0]) or 1.0]
+    bounds = ([0, 0.1, 1e-6], [np.inf, 5.0, np.inf])
+    try:
+        popt, _ = curve_fit(_hill, x, y, p0=p0, bounds=bounds, maxfev=10000)
+    except Exception as exc:  # noqa: BLE001
+        return ToolResult.fail(
+            f"Curve fit did not converge: {exc}",
+            recovery_hint="Try adstocking spend first, or check for outliers.",
+        )
+
+    beta, alpha, gamma = popt
+    pred = _hill(x, *popt)
+    ss_res = float(np.sum((y - pred) ** 2))
+    ss_tot = float(np.sum((y - y.mean()) ** 2)) + 1e-12
+    r2 = 1 - ss_res / ss_tot
+    shape = "S-shaped" if alpha > 1.05 else "concave (pure diminishing returns)"
+
+    return ToolResult.ok(
+        output=f"Hill fit: beta={beta:.2f}, alpha={alpha:.2f}, gamma={gamma:.2f}, R2={r2:.3f}",
+        summary=(
+            f"Saturation is {shape}. Half-saturation spend ~{gamma:.0f}; "
+            f"response ceiling ~{beta:.0f}. Fit R2={r2:.3f}."
+        ),
+        artifacts={
+            "beta": round(float(beta), 4),
+            "alpha": round(float(alpha), 4),
+            "gamma": round(float(gamma), 4),
+            "r2": round(r2, 4),
+        },
+        next_actions=[
+            "Feed these curve params into allocate_budget to optimise spend split.",
+            "If R2 is low, revisit adstock decay before trusting the curve.",
+        ],
+    )
+
+
+TOOL = Tool(
+    name="fit_saturation_curve",
+    description=(
+        "Fit a Hill saturation curve (diminishing returns) to paired spend/response "
+        "data for one channel. Returns ceiling (beta), shape (alpha), and "
+        "half-saturation point (gamma). Run on adstocked spend for best results."
+    ),
+    parameters={
+        "spend": {"type": "array", "items": {"type": "number"},
+                   "description": "Per-period spend (ideally adstocked)."},
+        "response": {"type": "array", "items": {"type": "number"},
+                      "description": "Per-period response/sales attributable to spend."},
+    },
+    fn=fit_saturation_curve,
+)

mixpilot-0.1.0.dist-info/METADATA

@@ -0,0 +1,121 @@
+Metadata-Version: 2.4
+Name: mixpilot
+Version: 0.1.0
+Summary: An agentic harness for marketing measurement: adstock, saturation, attribution, and budget allocation as typed agent tools with an eval suite.
+Author: Mohit Luthra
+License: MIT
+Project-URL: Homepage, https://github.com/mohit-luthra/mixpilot
+Keywords: marketing-mix-modeling,mmm,attribution,agents,llm,adstock,saturation
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+Requires-Dist: numpy>=1.24
+Requires-Dist: scipy>=1.10
+Requires-Dist: pydantic>=2.0
+Provides-Extra: agent
+Requires-Dist: anthropic>=0.39; extra == "agent"
+Provides-Extra: dev
+Requires-Dist: pytest>=7.0; extra == "dev"
+
+# MixPilot
+
+**An agentic harness for marketing measurement.**
+
+Everyone is building general-purpose agents. MixPilot is the opposite bet: a small,
+real agent runtime whose entire action space is the marketing-science toolkit —
+adstock, saturation, multi-touch attribution, budget optimisation, and a
+marketing-aware data-quality audit — wired as typed tools with structured results,
+an approval gate, and an eval suite that scores the agent's *method-selection
+judgment*.
+
+The thesis: in a domain agent, the tools are the product. A model can sound
+confident about marketing data; the hard part is knowing which method the data can
+actually support — and refusing the ones it can't. That judgment is what MixPilot
+encodes and tests.
+
+```bash
+pip install mixpilot           # tools only
+pip install "mixpilot[agent]"  # + the Anthropic-backed agent loop
+```
+
+## What's inside
+
+| Component | What it does | The lesson |
+|---|---|---|
+| `audit_data_quality` | nulls, negative spend, zero-variance, **multicollinearity** | The audit decides whether any later number is trustworthy at all |
+| `adstock_transform` | geometric carryover with half-life | Carryover before saturation, always |
+| `fit_saturation_curve` | Hill curve (β, α, γ) + R² | A low-R² curve is a warning, not a result |
+| `run_attribution_model` | last-touch / linear / **Markov removal-effect** | Match the model to the data shape, never overreach |
+| `allocate_budget` | constrained optimisation over saturation curves | Move money toward unsaturated marginal return |
+| `ToolResult` contract | summary + next_actions + recovery_hint on every call | A tool result is the next observation, not a log line |
+| Approval gate | mutating actions clear a policy gate outside the prompt | Safety lives in code, not prose |
+| Agent loop | turn budget + loop detection + stop conditions | The loop is a control system, not a while-tool-calls toy |
+| Eval suite | data shape → required/forbidden method | Test the judgment, not the prose |
+
+## The judgment, made concrete
+
+Same data, two attribution models:
+
+```python
+from mixpilot.tools.attribution import run_attribution_model
+
+paths  = [{"path": ["Social", "Search"], "converted": True}] * 40
+paths += [{"path": ["Social"],           "converted": False}] * 20
+
+run_attribution_model(paths, "last_touch").artifacts["share"]
+# {'Search': 1.0, 'Social': 0.0}   <- the assist is thrown away
+run_attribution_model(paths, "markov").artifacts["share"]
+# {'Search': 0.5, 'Social': 0.5}   <- both channels are necessary
+```
+
+Last-touch hands Social nothing. Markov's removal effect sees that every conversion
+needed Social first, and splits the credit. That gap — assist value — is the entire
+reason multi-touch attribution exists.
+
+## Running the agent
+
+```python
+from mixpilot import Agent
+from mixpilot.agent.client import AnthropicClient
+
+agent = Agent(AnthropicClient())   # needs ANTHROPIC_API_KEY
+result = agent.run(
+    "Here are 12 weeks of spend and sales for one channel ... "
+    "what's the saturation point and should we spend more?"
+)
+print(result.final_text)
+```
+
+The loop injects the client, so it runs against a real model in production and a
+scripted client in evals — no network needed to test the harness.
+
+## Evals: scoring method selection
+
+```bash
+python evals/run_evals.py          # offline, deterministic
+python evals/run_evals.py --live   # against a real model
+```
+
+Each case pairs a data shape with the methods it does and does not support. A case
+passes only if the agent uses every required tool and avoids every forbidden one —
+e.g. it must **not** run Markov attribution on single-touch data, and must audit
+before claiming per-channel effects on collinear spend.
+
+## Tests
+
+```bash
+python -m pytest -q     # 10 passing — domain math + harness contracts
+```
+
+The tests never call a model. They prove the adstock conserves mass, the Hill fit
+recovers known parameters, the Markov removal effect credits assists, the optimiser
+moves budget toward unsaturated channels, the audit catches multicollinearity, and
+the approval gate blocks mutating actions. Harness reliability that has nothing to do
+with model intelligence.
+
+## Scope
+
+This is deliberately small. No context compaction, no MCP, no subagents — those are
+solved problems in general harnesses. The point here is the opposite: how far you get
+when the action space is a real domain and the tools enforce the judgment.
+
+MIT licensed.

mixpilot-0.1.0.dist-info/RECORD

@@ -0,0 +1,19 @@
+mixpilot/__init__.py,sha256=q5wz41OcwOhBIgAWMJe8aeyyTmQFpspouaO1ON8m38M,683
+mixpilot/agent/__init__.py,sha256=3C_OCAb3bqBvpM6usMAB497w-WM5P6X9Bl6gUEKvJJE,155
+mixpilot/agent/client.py,sha256=lO-2ZzQ3SncoPHrSB7-C8J5eXGwr9gvX-R04qmQmmEU,1446
+mixpilot/agent/groq_client.py,sha256=WRu2VwoYUE1N-XoiMJg_EDp-kykiORZYjlY2mRKpN6U,4596
+mixpilot/agent/loop.py,sha256=k7fYaOwdUWjInTr4C7Kk9DgDDviL5uaXgG9doLFUM9s,4536
+mixpilot/safety/__init__.py,sha256=HmOWG7fLnSYp9EdLTl4VuWOpbX4EsZl6019f6zs_5Ko,102
+mixpilot/safety/approval.py,sha256=AvH060ADUO4HC_MgOe8DE9zDy9DO99TKa-yvO20fRck,1383
+mixpilot/tools/__init__.py,sha256=roZIer8m05a1bFKvQe3y7YRT6CIfYh08Ttubt-6_5A8,143
+mixpilot/tools/adstock.py,sha256=WwVTqqh6D6r5bVwOHjNv5Nz0yt93U94DGg_iF5N3yBA,2810
+mixpilot/tools/attribution.py,sha256=mZfilJVnv_Abz6pxlBWwJjzTZuGZT0Gc9Mg_HuoEkkM,5982
+mixpilot/tools/base.py,sha256=38FlB5azzFt02UPNGisoST7Qs-muNfOe0U3D1KQb5U0,3462
+mixpilot/tools/budget.py,sha256=_18l72HESeZiFWwK8ztG33RaweyaJcyPfbdOFemI6VE,3764
+mixpilot/tools/dataquality.py,sha256=lfDygb1MDHDNM2klISopGoyk2wRYO8mjIryvY0AbjVI,4242
+mixpilot/tools/registry.py,sha256=LhGEVR650EO0P15k-E2Ne76JHwPg4wfjnQNx71C7N9M,2166
+mixpilot/tools/saturation.py,sha256=ld3cKmY6KRiUNAJ6TZN7GILucvWCruu7s1VgNfJqVeI,3612
+mixpilot-0.1.0.dist-info/METADATA,sha256=cWYGfZi54oBDdGy-M7UG6TQ9MZnxNAEZxtC3woobkQE,5234
+mixpilot-0.1.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+mixpilot-0.1.0.dist-info/top_level.txt,sha256=6BA2FqJnYiBkdycD1u8D8B0tXKLpv3QR2CryuzmFV8Y,9
+mixpilot-0.1.0.dist-info/RECORD,,

mixpilot-0.1.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

mixpilot-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+mixpilot