mixpilot 0.1.0__tar.gz

mixpilot-0.1.0/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,103 @@
+# 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/pyproject.toml

@@ -0,0 +1,28 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "mixpilot"
+version = "0.1.0"
+description = "An agentic harness for marketing measurement: adstock, saturation, attribution, and budget allocation as typed agent tools with an eval suite."
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+authors = [{ name = "Mohit Luthra" }]
+keywords = ["marketing-mix-modeling", "mmm", "attribution", "agents", "llm", "adstock", "saturation"]
+dependencies = ["numpy>=1.24", "scipy>=1.10", "pydantic>=2.0"]
+
+[project.optional-dependencies]
+agent = ["anthropic>=0.39"]
+dev = ["pytest>=7.0"]
+
+[project.urls]
+Homepage = "https://github.com/mohit-luthra/mixpilot"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+pythonpath = ["src"]
+testpaths = ["tests"]

mixpilot-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

mixpilot-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/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-0.1.0/src/mixpilot/safety/__init__.py

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

mixpilot-0.1.0/src/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-0.1.0/src/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"]