adaptive-iteration 0.1.0__py3-none-any.whl

adaptive_iteration/__init__.py

@@ -0,0 +1,12 @@
+"""adaptive_iteration — Domain-agnostic adaptive experiment framework.
+
+Import paths:
+    from adaptive_iteration.core.experiment import Experiment, Variant, ExperimentState
+    from adaptive_iteration.core.ledger import Ledger
+    from adaptive_iteration.core.analyzer import Analyzer
+    from adaptive_iteration.core.hypothesis import HypothesisEngine
+    from adaptive_iteration.core.config import AdaptiveConfig
+    from adaptive_iteration.adapters.base import DomainAdapter
+    from adaptive_iteration.adapters.short_video import ShortVideoAdapter
+"""
+__version__ = "0.1.0"

adaptive_iteration/adapters/__init__.py

@@ -0,0 +1,5 @@
+# adaptive_iteration.adapters — DomainAdapter interface + example implementations
+from .base import DomainAdapter
+from .short_video import ShortVideoAdapter
+
+__all__ = ["DomainAdapter", "ShortVideoAdapter"]

adaptive_iteration/adapters/base.py

@@ -0,0 +1,81 @@
+"""adapters/base.py — DomainAdapter ABC.
+
+Every domain (short video, blog, email, ...) must implement these three methods.
+core/ never imports from here; HypothesisEngine receives the outputs as plain dicts/strings.
+"""
+from __future__ import annotations
+
+from abc import ABC, abstractmethod
+from typing import Any
+
+
+class DomainAdapter(ABC):
+    """Bridge between adaptive_iteration.core and a concrete external system.
+
+    Three required methods
+    ----------------------
+    collect_metrics(item_ids)
+        Pull raw metric data for the given item IDs.
+        Returns a list of dicts, one per item. Each dict must include at least
+        the item's ID under some consistent key (e.g. "id").
+
+    get_signals(metrics)
+        Normalise raw metrics into framework-friendly signals:
+          - "primary_metric": float  (the single most-important KPI for ranking)
+          - "secondary_metrics": dict  (any additional useful metrics)
+        Returns a dict.
+
+    format_context(top_items, bottom_items)
+        Produce a human-readable text block describing top and bottom performers.
+        This is injected verbatim into the HypothesisEngine prompt.
+        Returns a str.
+    """
+
+    # ── Required ───────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    def collect_metrics(self, item_ids: list[str]) -> list[dict[str, Any]]:
+        """Fetch raw metrics for *item_ids* from the external system.
+
+        Parameters
+        ----------
+        item_ids : list of platform-specific IDs (video IDs, post IDs, …)
+
+        Returns
+        -------
+        list[dict]
+            One dict per item. Shape is domain-specific; must be consistent with
+            what get_signals() expects.
+        """
+        ...
+
+    @abstractmethod
+    def get_signals(self, metrics: list[dict[str, Any]]) -> dict[str, Any]:
+        """Normalise raw metrics into a standard signals dict.
+
+        Expected output schema
+        ----------------------
+        {
+            "primary_metric": <float>,          # main ranking KPI
+            "secondary_metrics": {<str>: <float>, ...},
+        }
+        """
+        ...
+
+    @abstractmethod
+    def format_context(
+        self,
+        top_items: list[dict[str, Any]],
+        bottom_items: list[dict[str, Any]],
+    ) -> str:
+        """Return a text block describing top vs bottom performers.
+
+        Used verbatim in the HypothesisEngine LLM prompt.
+        """
+        ...
+
+    # ── Optional convenience ───────────────────────────────────────────────────
+
+    def describe(self) -> str:
+        """Short human-readable description of this adapter (for logs/docs)."""
+        return self.__class__.__name__

adaptive_iteration/adapters/short_video.py

@@ -0,0 +1,178 @@
+"""adapters/short_video.py — Example ShortVideoAdapter.
+
+This is a reference implementation showing how to build a DomainAdapter
+for short-form video platforms (e.g. YouTube Shorts, Instagram Reels).
+
+In a real deployment, replace `collect_metrics` and `get_signals` with
+calls to your actual analytics backend.
+
+Usage
+-----
+    from adaptive_iteration.adapters.short_video import ShortVideoAdapter
+
+    adapter = ShortVideoAdapter(platform="youtube")
+    metrics = adapter.collect_metrics(["video_001", "video_002"])
+    signals = adapter.get_signals(metrics)
+"""
+from __future__ import annotations
+
+import random
+from typing import Any
+
+from .base import DomainAdapter
+
+
+class ShortVideoAdapter(DomainAdapter):
+    """Example DomainAdapter for short-video platforms.
+
+    Supports "youtube" and "instagram" as platform targets.
+    Metrics are simulated — replace with your real analytics calls.
+
+    Parameters
+    ----------
+    platform : "youtube" or "instagram"
+    """
+
+    SUPPORTED_PLATFORMS = ("youtube", "instagram")
+
+    def __init__(self, platform: str) -> None:
+        if platform not in self.SUPPORTED_PLATFORMS:
+            raise ValueError(
+                f"Unsupported platform {platform!r}. "
+                f"Choose from {self.SUPPORTED_PLATFORMS}."
+            )
+        self.platform = platform
+
+    # ── DomainAdapter interface ────────────────────────────────────────────────
+
+    def collect_metrics(self, item_ids: list[str]) -> list[dict[str, Any]]:
+        """Fetch metrics for each item ID.
+
+        Replace this with real API calls to your analytics provider.
+        This implementation returns simulated data for illustration.
+        """
+        results = []
+        for item_id in item_ids:
+            if self.platform == "youtube":
+                results.append({
+                    "id": item_id,
+                    "views": random.randint(500, 50_000),
+                    "avg_view_pct": round(random.uniform(30, 90), 1),
+                    "avg_view_sec": round(random.uniform(15, 75), 1),
+                    "like_rate": round(random.uniform(0.5, 8.0), 2),
+                    "subscribers_gained": random.randint(0, 50),
+                })
+            else:  # instagram
+                reach = random.randint(200, 20_000)
+                likes = random.randint(10, int(reach * 0.15))
+                results.append({
+                    "id": item_id,
+                    "reach": reach,
+                    "likes": likes,
+                    "saves": random.randint(0, int(reach * 0.05)),
+                    "shares": random.randint(0, int(reach * 0.03)),
+                    "comments": random.randint(0, int(reach * 0.02)),
+                    "avg_watch_time_ms": random.randint(3_000, 30_000),
+                    "total_interactions": likes + random.randint(5, 100),
+                })
+        return results
+
+    def get_signals(self, metrics: list[dict[str, Any]]) -> dict[str, Any]:
+        """Normalise raw metrics into framework signals.
+
+        YouTube  → primary_metric = avg_view_pct (0–100)
+        Instagram → primary_metric = engagement_score
+                    = (saves×3 + shares×2 + comments×2 + likes) / reach × 100
+        """
+        if not metrics:
+            return {"primary_metric": 0.0, "secondary_metrics": {}}
+
+        if self.platform == "youtube":
+            return self._yt_signals(metrics)
+        return self._ig_signals(metrics)
+
+    def format_context(
+        self,
+        top_items: list[dict[str, Any]],
+        bottom_items: list[dict[str, Any]],
+    ) -> str:
+        lines = [f"Platform: {self.platform}"]
+        lines.append("\nTop performers:")
+        for item in top_items:
+            lines.append(self._fmt(item))
+        lines.append("\nBottom performers:")
+        for item in bottom_items:
+            lines.append(self._fmt(item))
+        return "\n".join(lines)
+
+    def describe(self) -> str:
+        return f"ShortVideoAdapter(platform={self.platform!r})"
+
+    # ── Internal ───────────────────────────────────────────────────────────────
+
+    def _yt_signals(self, metrics: list[dict]) -> dict[str, Any]:
+        valid = [m for m in metrics if m.get("avg_view_pct") is not None]
+        if not valid:
+            return {"primary_metric": 0.0, "secondary_metrics": {}}
+        n = len(metrics)
+        return {
+            "primary_metric": round(
+                sum(m["avg_view_pct"] for m in valid) / len(valid), 2
+            ),
+            "secondary_metrics": {
+                "views":              round(sum(m.get("views", 0) for m in metrics) / n, 1),
+                "like_rate":          round(sum(m.get("like_rate", 0) for m in metrics) / n, 3),
+                "avg_view_sec":       round(sum(m.get("avg_view_sec", 0) for m in metrics) / n, 1),
+                "subscribers_gained": round(sum(m.get("subscribers_gained", 0) for m in metrics) / n, 2),
+            },
+        }
+
+    def _ig_signals(self, metrics: list[dict]) -> dict[str, Any]:
+        valid = [m for m in metrics if m.get("reach", 0) > 0]
+        if not valid:
+            return {"primary_metric": 0.0, "secondary_metrics": {}}
+        n = len(metrics)
+
+        def _eng(m: dict) -> float:
+            reach = m.get("reach", 1)
+            return (
+                m.get("saves", 0) * 3
+                + m.get("shares", 0) * 2
+                + m.get("comments", 0) * 2
+                + m.get("likes", 0)
+            ) / reach * 100
+
+        return {
+            "primary_metric": round(sum(_eng(m) for m in valid) / len(valid), 4),
+            "secondary_metrics": {
+                "reach":            round(sum(m.get("reach", 0) for m in metrics) / n, 1),
+                "like_rate":        round(
+                    sum(m.get("likes", 0) / max(m.get("reach", 1), 1) * 100 for m in metrics) / n, 3
+                ),
+                "avg_watch_time_s": round(
+                    sum(m.get("avg_watch_time_ms", 0) for m in metrics) / n / 1000, 2
+                ),
+                "shares":           round(sum(m.get("shares", 0) for m in metrics) / n, 2),
+                "saved":            round(sum(m.get("saves", 0) for m in metrics) / n, 2),
+                "total_interactions": round(sum(m.get("total_interactions", 0) for m in metrics) / n, 2),
+            },
+        }
+
+    def _fmt(self, item: dict) -> str:
+        item_id = item.get("id", "?")
+        if self.platform == "youtube":
+            return (
+                f"  [{item_id}] "
+                f"avg_view_pct={item.get('avg_view_pct')}%  "
+                f"views={item.get('views')}  "
+                f"like_rate={item.get('like_rate')}%"
+            )
+        reach = item.get("reach", 0)
+        likes = item.get("likes", 0)
+        lr = round(likes / reach * 100, 2) if reach > 0 else 0.0
+        return (
+            f"  [{item_id}] "
+            f"like_rate={lr}%  "
+            f"reach={reach}  "
+            f"avg_watch={item.get('avg_watch_time_ms', 0) // 1000}s"
+        )

adaptive_iteration/core/__init__.py

@@ -0,0 +1 @@
+# adaptive_iteration.core — pure Python, zero domain dependencies

adaptive_iteration/core/analyzer.py

@@ -0,0 +1,153 @@
+"""core/analyzer.py — Pattern detection from ledger records.
+
+Finds top / bottom performers and common features, computes per-dimension variance,
+and produces a structured AnalysisResult for use by HypothesisEngine.
+"""
+from __future__ import annotations
+
+import statistics
+from dataclasses import dataclass
+from typing import Any, Optional
+
+from .ledger import Ledger
+
+
+@dataclass
+class DimensionStats:
+    """Variance and mean for a single metric dimension."""
+    name: str
+    mean: float
+    variance: float
+    stdev: float
+    count: int
+
+
+@dataclass
+class AnalysisResult:
+    """Output of Analyzer.analyze()."""
+    domain: str
+    total_records: int
+    top_performers: list[dict[str, Any]]        # records with highest primary_metric
+    bottom_performers: list[dict[str, Any]]      # records with lowest primary_metric
+    top_features: dict[str, Any]                 # common variable→variant among top
+    bottom_features: dict[str, Any]              # common variable→variant among bottom
+    dimension_stats: list[DimensionStats]        # per-metric variance across all records
+    winning_patterns: dict[str, str]             # variable → variant that won most often
+
+
+class Analyzer:
+    """Derives insights from a Ledger.
+
+    Parameters
+    ----------
+    ledger       : Ledger instance to analyse
+    primary_metric : the metric key to rank performers by (e.g. "avg_view_pct")
+    top_n        : how many top/bottom performers to surface
+    """
+
+    def __init__(
+        self,
+        ledger: Ledger,
+        primary_metric: str = "primary_metric",
+        top_n: int = 5,
+    ) -> None:
+        self.ledger = ledger
+        self.primary_metric = primary_metric
+        self.top_n = top_n
+
+    # ── Public ─────────────────────────────────────────────────────────────────
+
+    def analyze(self, domain: Optional[str] = None) -> AnalysisResult:
+        """Run full analysis for *domain* (or all domains if None)."""
+        records = self.ledger.query(domain=domain) if domain else self.ledger.records
+
+        if not records:
+            return AnalysisResult(
+                domain=domain or "all",
+                total_records=0,
+                top_performers=[],
+                bottom_performers=[],
+                top_features={},
+                bottom_features={},
+                dimension_stats=[],
+                winning_patterns={},
+            )
+
+        # Sort by primary metric (records without it go to the bottom)
+        def _primary(r: dict) -> float:
+            return float(r.get("metric_values", {}).get(self.primary_metric) or 0.0)
+
+        ranked = sorted(records, key=_primary, reverse=True)
+        top = ranked[: self.top_n]
+        bottom = ranked[-self.top_n:]
+
+        return AnalysisResult(
+            domain=domain or "all",
+            total_records=len(records),
+            top_performers=top,
+            bottom_performers=bottom,
+            top_features=self._common_features(top),
+            bottom_features=self._common_features(bottom),
+            dimension_stats=self._dimension_stats(records),
+            winning_patterns=self._winning_patterns(records),
+        )
+
+    # ── Internal ───────────────────────────────────────────────────────────────
+
+    def _common_features(self, records: list[dict]) -> dict[str, Any]:
+        """Return {variable: variant} pairs that appear in >50% of records."""
+        if not records:
+            return {}
+        counts: dict[str, dict[str, int]] = {}
+        for r in records:
+            var = r.get("variable", "")
+            val = r.get("variant", "")
+            if var and val:
+                counts.setdefault(var, {}).setdefault(val, 0)
+                counts[var][val] += 1
+
+        threshold = len(records) * 0.5
+        result: dict[str, Any] = {}
+        for var, val_counts in counts.items():
+            best_val, best_count = max(val_counts.items(), key=lambda x: x[1])
+            if best_count >= threshold:
+                result[var] = best_val
+        return result
+
+    def _dimension_stats(self, records: list[dict]) -> list[DimensionStats]:
+        """Compute mean / variance for every metric key found in records."""
+        all_metrics: dict[str, list[float]] = {}
+        for r in records:
+            for k, v in r.get("metric_values", {}).items():
+                if isinstance(v, (int, float)) and v is not None:
+                    all_metrics.setdefault(k, []).append(float(v))
+
+        stats: list[DimensionStats] = []
+        for name, values in all_metrics.items():
+            if len(values) < 2:
+                continue
+            mean = statistics.mean(values)
+            var  = statistics.variance(values)
+            std  = statistics.stdev(values)
+            stats.append(DimensionStats(
+                name=name, mean=round(mean, 4), variance=round(var, 4),
+                stdev=round(std, 4), count=len(values),
+            ))
+        return sorted(stats, key=lambda s: s.variance, reverse=True)
+
+    def _winning_patterns(self, records: list[dict]) -> dict[str, str]:
+        """For each variable, find the variant that won most frequently."""
+        win_counts: dict[str, dict[str, int]] = {}
+        for r in records:
+            if not r.get("winner"):
+                continue
+            var = r.get("variable", "")
+            val = r.get("variant", "")
+            if var and val:
+                win_counts.setdefault(var, {}).setdefault(val, 0)
+                win_counts[var][val] += 1
+
+        return {
+            var: max(val_counts, key=val_counts.get)
+            for var, val_counts in win_counts.items()
+        }

adaptive_iteration/core/config.py

@@ -0,0 +1,106 @@
+"""core/config.py — AdaptiveConfig: read/write JSON config with winner hints support.
+
+Config file schema (example):
+{
+    "domain": "short_video",
+    "primary_metric": "avg_view_pct",
+    "min_items_per_variant": 3,
+    "winner_hints": {
+        "hook_type": "question",
+        "cta_style": "soft"
+    },
+    "extra": {}
+}
+"""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+from typing import Any, Optional
+
+_DEFAULTS: dict[str, Any] = {
+    "domain":                "default",
+    "primary_metric":        "primary_metric",
+    "min_items_per_variant": 3,
+    "winner_hints":          {},
+    "extra":                 {},
+}
+
+
+class AdaptiveConfig:
+    """Lightweight JSON config bag with typed accessor helpers.
+
+    Parameters
+    ----------
+    path : where to load from / save to (created on first save if absent)
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._data: dict[str, Any] = dict(_DEFAULTS)
+        if path.exists():
+            try:
+                loaded = json.loads(path.read_text(encoding="utf-8"))
+                self._data.update(loaded)
+            except (json.JSONDecodeError, OSError):
+                pass
+
+    # ── Accessors ──────────────────────────────────────────────────────────────
+
+    def get(self, key: str, default: Any = None) -> Any:
+        return self._data.get(key, default)
+
+    def set(self, key: str, value: Any) -> None:
+        self._data[key] = value
+        self._flush()
+
+    def update(self, mapping: dict[str, Any]) -> None:
+        self._data.update(mapping)
+        self._flush()
+
+    # ── Winner hints ───────────────────────────────────────────────────────────
+
+    def set_winner_hint(self, variable: str, variant_label: str) -> None:
+        """Record which variant won for *variable*."""
+        hints = self._data.setdefault("winner_hints", {})
+        hints[variable] = variant_label
+        self._flush()
+
+    def get_winner_hint(self, variable: str) -> Optional[str]:
+        return self._data.get("winner_hints", {}).get(variable)
+
+    def all_winner_hints(self) -> dict[str, str]:
+        return dict(self._data.get("winner_hints", {}))
+
+    # ── Convenience ────────────────────────────────────────────────────────────
+
+    @property
+    def domain(self) -> str:
+        return str(self._data.get("domain", "default"))
+
+    @property
+    def primary_metric(self) -> str:
+        return str(self._data.get("primary_metric", "primary_metric"))
+
+    @property
+    def min_items_per_variant(self) -> int:
+        return int(self._data.get("min_items_per_variant", 3))
+
+    def to_dict(self) -> dict[str, Any]:
+        return dict(self._data)
+
+    # ── Persistence ────────────────────────────────────────────────────────────
+
+    def _flush(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(self._data, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    def save(self) -> None:
+        """Explicit save (normally auto-saved on every set/update)."""
+        self._flush()
+
+    def __repr__(self) -> str:
+        return f"AdaptiveConfig(path={self.path!r}, domain={self.domain!r})"

adaptive_iteration/core/experiment.py

@@ -0,0 +1,125 @@
+"""core/experiment.py — Experiment / Variant dataclasses + ExperimentState.
+
+All fields are plain Python types so they round-trip cleanly through JSON.
+"""
+from __future__ import annotations
+
+import uuid
+from dataclasses import dataclass, field
+from typing import Any, Literal, Optional
+
+
+@dataclass
+class Variant:
+    """One arm of an experiment."""
+    label: str
+    params: dict[str, Any] = field(default_factory=dict)
+    hint: Optional[str] = None          # short text cue for downstream renderers
+
+    def to_dict(self) -> dict:
+        return {"label": self.label, "params": self.params, "hint": self.hint}
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Variant":
+        return cls(label=d["label"], params=d.get("params", {}), hint=d.get("hint"))
+
+
+@dataclass
+class Experiment:
+    """A single testable hypothesis with two variants (A/B).
+
+    Fields
+    ------
+    id          : short unique id (8-char hex by default)
+    domain      : e.g. "short_video", "blog_post", "email_campaign"
+    variable    : what's being tested, e.g. "hook_type", "cta_style"
+    description : human-readable summary of the hypothesis
+    variant_a   : control arm
+    variant_b   : challenger arm
+    tier        : priority tier (1 = run alone, 2 = can run in parallel, 3 = no A/B)
+    started     : ISO date string when experiment went active, or None
+    concluded   : ISO date string when experiment was evaluated, or None
+    status      : "pending" | "active" | "concluded"
+    items       : list of {"item_id": str, "variant": str, ...} — produced units
+    """
+    id: str = field(default_factory=lambda: uuid.uuid4().hex[:8])
+    domain: str = ""
+    variable: str = ""
+    description: str = ""
+    variant_a: Variant = field(default_factory=lambda: Variant(label="control"))
+    variant_b: Variant = field(default_factory=lambda: Variant(label="variant"))
+    tier: int = 1
+    started: Optional[str] = None
+    concluded: Optional[str] = None
+    status: str = "pending"
+    mode: Literal["interleaved", "paired"] = "interleaved"
+    """Experiment execution mode.
+
+    - ``interleaved``: Different topics are assigned to variants in alternating
+      fashion.  Maximises throughput (Tier 2 experiments).  One topic → one
+      video → one variant.
+
+    - ``paired``: The *same* topic is used to produce two videos — one per
+      variant — in a single run.  This eliminates topic-level confounders and
+      yields cleaner causal inference.  Preferred for Tier 1 experiments where
+      the variable under test (e.g. subscribe_prompt, cta_style) is independent
+      of the topic itself.
+    """
+    items: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "id":          self.id,
+            "domain":      self.domain,
+            "variable":    self.variable,
+            "description": self.description,
+            "variant_a":   self.variant_a.to_dict(),
+            "variant_b":   self.variant_b.to_dict(),
+            "tier":        self.tier,
+            "started":     self.started,
+            "concluded":   self.concluded,
+            "status":      self.status,
+            "mode":        self.mode,
+            "items":       self.items,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "Experiment":
+        return cls(
+            id=d.get("id", uuid.uuid4().hex[:8]),
+            domain=d.get("domain", ""),
+            variable=d.get("variable", ""),
+            description=d.get("description", ""),
+            variant_a=Variant.from_dict(d.get("variant_a", {"label": "control"})),
+            variant_b=Variant.from_dict(d.get("variant_b", {"label": "variant"})),
+            tier=d.get("tier", 1),
+            started=d.get("started"),
+            concluded=d.get("concluded"),
+            status=d.get("status", "pending"),
+            mode=d.get("mode", "interleaved"),
+            items=d.get("items", []),
+        )
+
+
+@dataclass
+class ExperimentState:
+    """Persisted state for one domain's experiment pipeline."""
+    current: Optional[Experiment] = None
+    queue: list[Experiment] = field(default_factory=list)
+    history: list[dict[str, Any]] = field(default_factory=list)
+
+    def to_dict(self) -> dict:
+        return {
+            "current": self.current.to_dict() if self.current else {},
+            "queue":   [e.to_dict() for e in self.queue],
+            "history": self.history,
+        }
+
+    @classmethod
+    def from_dict(cls, d: dict) -> "ExperimentState":
+        current_raw = d.get("current", {})
+        return cls(
+            current=Experiment.from_dict(current_raw) if current_raw else None,
+            queue=[Experiment.from_dict(e) for e in d.get("queue", [])],
+            history=d.get("history", []),
+        )

adaptive_iteration/core/hypothesis.py

@@ -0,0 +1,190 @@
+"""core/hypothesis.py — HypothesisEngine: ledger + analysis → new Experiment candidates.
+
+Uses OpenAI Chat API. Prompt structure:
+  system  : role + output schema
+  user    : past experiment results + top/bottom performer context
+
+Output: list of Experiment dicts (JSON), one per hypothesis candidate.
+"""
+from __future__ import annotations
+
+import json
+import re
+from pathlib import Path
+from typing import Any
+
+from .analyzer import AnalysisResult
+from .experiment import Experiment, Variant
+from .ledger import Ledger
+
+_SYSTEM_PROMPT = """\
+You are an adaptive experimentation strategist. Your job is to analyse past A/B experiment \
+results and suggest the next highest-value hypotheses to test.
+
+Rules:
+- Each hypothesis must test exactly ONE variable (to avoid confounding).
+- Build on what worked: if a variable already has a known winner, either skip it or propose \
+  a refined follow-up.
+- Prioritise variables with high variance in the metrics — they have the most room for \
+  improvement.
+- Avoid re-testing already conclusive experiments unless the context has meaningfully changed.
+- Output ONLY a valid JSON array. Each element must match:
+
+{
+  "variable":    "<what is being tested, snake_case>",
+  "description": "<one-sentence hypothesis>",
+  "variant_a":   {"label": "<control label>", "params": {}, "hint": "<optional>"},
+  "variant_b":   {"label": "<challenger label>", "params": {}, "hint": "<optional>"},
+  "tier":        <1 | 2 | 3>,
+  "rationale":   "<why this is worth testing now>"
+}
+
+Tier meanings:
+  1 = high-impact, must run alone
+  2 = moderate-impact, can run in parallel with other Tier 2
+  3 = no A/B needed, recommend directly based on research
+"""
+
+
+class HypothesisEngine:
+    """Generate new Experiment candidates from past ledger data.
+
+    Parameters
+    ----------
+    ledger      : Ledger instance (source of truth for past results)
+    api_key     : OpenAI API key (or path to a file containing it)
+    model       : OpenAI chat model to use
+    max_candidates : how many hypotheses to request
+    """
+
+    def __init__(
+        self,
+        ledger: Ledger,
+        api_key: str | Path,
+        model: str = "gpt-5.4-mini",
+        max_candidates: int = 5,
+    ) -> None:
+        self.ledger = ledger
+        self.model = model
+        self.max_candidates = max_candidates
+
+        if isinstance(api_key, Path) or (isinstance(api_key, str) and "\n" not in api_key and len(api_key) < 200):
+            p = Path(api_key)
+            if p.exists():
+                self._api_key = p.read_text().strip()
+            else:
+                self._api_key = api_key  # treat as literal key string
+        else:
+            self._api_key = api_key
+
+    # ── Public ─────────────────────────────────────────────────────────────────
+
+    def generate(
+        self,
+        domain: str,
+        analysis: AnalysisResult,
+        domain_context: str = "",
+        extra_instructions: str = "",
+    ) -> list[Experiment]:
+        """Call LLM and return a list of Experiment candidates.
+
+        Parameters
+        ----------
+        domain          : domain identifier (e.g. "short_video")
+        analysis        : output of Analyzer.analyze()
+        domain_context  : adapter-provided text about top/bottom performers
+        extra_instructions : any domain-specific guidance to append to the prompt
+        """
+        from openai import OpenAI
+
+        client = OpenAI(api_key=self._api_key)
+
+        user_message = self._build_user_message(
+            domain=domain,
+            analysis=analysis,
+            domain_context=domain_context,
+            extra_instructions=extra_instructions,
+        )
+
+        resp = client.chat.completions.create(
+            model=self.model,
+            messages=[
+                {"role": "system", "content": _SYSTEM_PROMPT},
+                {"role": "user",   "content": user_message},
+            ],
+            max_completion_tokens=2000,
+        )
+
+        raw = resp.choices[0].message.content.strip()
+        candidates = self._parse_response(raw)
+        experiments = []
+        for c in candidates:
+            exp = Experiment(
+                domain=domain,
+                variable=c.get("variable", "unknown"),
+                description=c.get("description", ""),
+                variant_a=Variant.from_dict(c.get("variant_a", {"label": "control"})),
+                variant_b=Variant.from_dict(c.get("variant_b", {"label": "variant"})),
+                tier=int(c.get("tier", 2)),
+            )
+            experiments.append(exp)
+
+        return experiments
+
+    # ── Internal ───────────────────────────────────────────────────────────────
+
+    def _build_user_message(
+        self,
+        domain: str,
+        analysis: AnalysisResult,
+        domain_context: str,
+        extra_instructions: str,
+    ) -> str:
+        parts: list[str] = [f"Domain: {domain}"]
+
+        # Past results summary
+        records = self.ledger.query(domain=domain)
+        if records:
+            concluded = [r for r in records if r.get("winner") is not None]
+            parts.append(f"\n## Past experiments ({len(concluded)} concluded, {len(records)} total records)")
+            # Group by experiment_id
+            by_exp: dict[str, list] = {}
+            for r in concluded:
+                eid = r.get("experiment_id", "?")
+                by_exp.setdefault(eid, []).append(r)
+            for eid, exp_records in list(by_exp.items())[-10:]:  # last 10 experiments
+                winners = [r for r in exp_records if r.get("winner")]
+                w_str = f"winner={winners[0]['variant']} ({winners[0]['metric_values']})" if winners else "inconclusive"
+                var = exp_records[0].get("variable", "?")
+                parts.append(f"  - [{eid}] variable={var} → {w_str}")
+        else:
+            parts.append("\n## Past experiments: none yet — this is the first cycle.")
+
+        # Winning patterns
+        if analysis.winning_patterns:
+            parts.append("\n## Known winners by variable\n" +
+                         "\n".join(f"  {k}: {v}" for k, v in analysis.winning_patterns.items()))
+
+        # High-variance dimensions
+        if analysis.dimension_stats:
+            parts.append("\n## Metric variance (highest = most opportunity)")
+            for ds in analysis.dimension_stats[:5]:
+                parts.append(f"  {ds.name}: variance={ds.variance:.3f}, mean={ds.mean:.3f} (n={ds.count})")
+
+        # Domain-provided context (top/bottom performers)
+        if domain_context:
+            parts.append(f"\n## Domain context (top vs bottom performers)\n{domain_context}")
+
+        parts.append(
+            f"\n## Task\nSuggest {self.max_candidates} next experiment candidates for domain '{domain}'."
+        )
+        if extra_instructions:
+            parts.append(f"\nAdditional guidance:\n{extra_instructions}")
+
+        return "\n".join(parts)
+
+    @staticmethod
+    def _parse_response(raw: str) -> list[dict[str, Any]]:
+        # Strip markdown code fences if present
+        raw = re.sub(r"^```[a-z]*\n?|\n?```$", "", raw.strip())
+        return json.loads(raw)

adaptive_iteration/core/ledger.py

@@ -0,0 +1,119 @@
+"""core/ledger.py — Domain-agnostic JSON ledger.
+
+Replaces results.tsv with a structured, queryable JSON store.
+
+Record schema
+-------------
+{
+    "domain":        str,          # e.g. "short_video"
+    "experiment_id": str,
+    "variable":      str,          # what was tested
+    "variant":       str,          # variant label ("control" / "challenger" / ...)
+    "metric_values": dict,         # raw metric snapshot, e.g. {"avg_view_pct": 45.2}
+    "winner":        bool | None,  # True if this variant won
+    "timestamp":     str           # ISO-8601 datetime
+}
+"""
+from __future__ import annotations
+
+import json
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any, Optional
+
+
+class Ledger:
+    """Append-only JSON ledger stored at *path*.
+
+    Usage
+    -----
+    ledger = Ledger(Path("data/ledger.json"))
+    ledger.append(
+        domain="short_video",
+        experiment_id="abc123",
+        variable="hook_type",
+        variant="question",
+        metric_values={"avg_view_pct": 52.1, "like_rate": 3.2},
+        winner=True,
+    )
+    records = ledger.query(domain="short_video")
+    """
+
+    def __init__(self, path: Path) -> None:
+        self.path = path
+        self._records: list[dict[str, Any]] = []
+        if path.exists():
+            try:
+                self._records = json.loads(path.read_text(encoding="utf-8"))
+            except (json.JSONDecodeError, OSError):
+                self._records = []
+
+    # ── Write ──────────────────────────────────────────────────────────────────
+
+    def append(
+        self,
+        domain: str,
+        experiment_id: str,
+        variable: str,
+        variant: str,
+        metric_values: dict[str, Any],
+        winner: Optional[bool] = None,
+        timestamp: Optional[str] = None,
+    ) -> dict[str, Any]:
+        record = {
+            "domain":        domain,
+            "experiment_id": experiment_id,
+            "variable":      variable,
+            "variant":       variant,
+            "metric_values": metric_values,
+            "winner":        winner,
+            "timestamp":     timestamp or datetime.now(timezone.utc).isoformat(),
+        }
+        self._records.append(record)
+        self._flush()
+        return record
+
+    def _flush(self) -> None:
+        self.path.parent.mkdir(parents=True, exist_ok=True)
+        self.path.write_text(
+            json.dumps(self._records, ensure_ascii=False, indent=2),
+            encoding="utf-8",
+        )
+
+    # ── Read ───────────────────────────────────────────────────────────────────
+
+    @property
+    def records(self) -> list[dict[str, Any]]:
+        return list(self._records)
+
+    def query(
+        self,
+        domain: Optional[str] = None,
+        variable: Optional[str] = None,
+        experiment_id: Optional[str] = None,
+        winners_only: bool = False,
+    ) -> list[dict[str, Any]]:
+        """Return filtered records. All filters are ANDed together."""
+        result = self._records
+        if domain is not None:
+            result = [r for r in result if r.get("domain") == domain]
+        if variable is not None:
+            result = [r for r in result if r.get("variable") == variable]
+        if experiment_id is not None:
+            result = [r for r in result if r.get("experiment_id") == experiment_id]
+        if winners_only:
+            result = [r for r in result if r.get("winner") is True]
+        return list(result)
+
+    def all_domains(self) -> list[str]:
+        return sorted({r["domain"] for r in self._records if "domain" in r})
+
+    def all_variables(self, domain: Optional[str] = None) -> list[str]:
+        records = self.query(domain=domain) if domain else self._records
+        return sorted({r["variable"] for r in records if "variable" in r})
+
+    def __len__(self) -> int:
+        return len(self._records)
+
+    def __repr__(self) -> str:
+        return f"Ledger(path={self.path!r}, records={len(self._records)})"

adaptive_iteration-0.1.0.dist-info/METADATA

@@ -0,0 +1,165 @@
+Metadata-Version: 2.4
+Name: adaptive-iteration
+Version: 0.1.0
+Summary: Domain-agnostic adaptive experimentation framework: experiment → measure → learn → challenge.
+Project-URL: Homepage, https://github.com/imaknas/adaptive-iteration
+Project-URL: Repository, https://github.com/imaknas/adaptive-iteration
+License: MIT
+Requires-Python: >=3.10
+Requires-Dist: openai>=1.0.0
+Description-Content-Type: text/markdown
+
+# adaptive_iteration
+
+**Domain-agnostic adaptive experimentation framework.**
+
+A lightweight Python framework that abstracts the **experiment → measure → learn → challenge**
+cycle into reusable components. Bring your own domain; the framework handles the rest.
+
+---
+
+## What It Is
+
+```
+adaptive_iteration/
+├── core/               # pure Python stdlib, zero domain deps
+│   ├── experiment.py   # Experiment / Variant dataclasses + ExperimentState
+│   ├── ledger.py       # JSON append-only results ledger
+│   ├── analyzer.py     # top/bottom performer detection, variance per dimension
+│   ├── hypothesis.py   # HypothesisEngine: ledger + analysis → LLM → Experiment candidates
+│   └── config.py       # AdaptiveConfig: JSON config + winner hints
+└── adapters/
+    ├── base.py         # DomainAdapter ABC (3 methods to implement)
+    └── short_video.py  # Example adapter: YouTube + Instagram (simulated data)
+```
+
+---
+
+## Installation
+
+```bash
+# with uv (recommended)
+uv add adaptive-iteration
+
+# with pip
+pip install adaptive-iteration
+```
+
+Requires Python 3.10+. The only runtime dependency is `openai` (used only in
+`HypothesisEngine`; the rest of `core/` is stdlib-only).
+
+---
+
+## Quick Start
+
+```python
+import os
+from pathlib import Path
+from adaptive_iteration.core.ledger import Ledger
+from adaptive_iteration.core.analyzer import Analyzer
+from adaptive_iteration.core.hypothesis import HypothesisEngine
+from adaptive_iteration.core.config import AdaptiveConfig
+
+# 1. Load / create config
+cfg = AdaptiveConfig(Path("data/adaptive_config.json"))
+cfg.update({"domain": "my_domain", "primary_metric": "conversion_rate"})
+
+# 2. Open ledger
+ledger = Ledger(Path("data/adaptive_ledger.json"))
+
+# 3. Record experiment results
+ledger.append(
+    domain="my_domain",
+    experiment_id="exp001",
+    variable="cta_style",
+    variant="soft",
+    metric_values={"conversion_rate": 4.2, "bounce_rate": 31.0},
+    winner=True,
+)
+
+# 4. Analyse
+analyzer = Analyzer(ledger, primary_metric="conversion_rate")
+analysis = analyzer.analyze(domain="my_domain")
+print(f"Top performers: {[p['variant'] for p in analysis.top_performers]}")
+print(f"Winning patterns: {analysis.winning_patterns}")
+
+# 5. Generate next hypotheses (requires OPENAI_API_KEY)
+engine = HypothesisEngine(
+    ledger=ledger,
+    api_key=os.environ["OPENAI_API_KEY"],
+)
+candidates = engine.generate(domain="my_domain", analysis=analysis)
+for exp in candidates:
+    print(f"  [{exp.tier}] {exp.variable}: {exp.description}")
+```
+
+---
+
+## Integrating a New Domain
+
+Subclass `DomainAdapter` and implement three methods:
+
+```python
+from adaptive_iteration.adapters.base import DomainAdapter
+
+class MyDomainAdapter(DomainAdapter):
+
+    def collect_metrics(self, item_ids: list[str]) -> list[dict]:
+        """Pull raw metrics from your external system for each item_id."""
+        results = []
+        for item_id in item_ids:
+            raw = my_api.get_metrics(item_id)
+            results.append({"id": item_id, **raw})
+        return results
+
+    def get_signals(self, metrics: list[dict]) -> dict:
+        """Normalise to framework signals."""
+        primary = sum(m["conversion_rate"] for m in metrics) / len(metrics)
+        return {
+            "primary_metric": primary,
+            "secondary_metrics": {
+                "bounce_rate": sum(m["bounce_rate"] for m in metrics) / len(metrics),
+            },
+        }
+
+    def format_context(self, top_items, bottom_items) -> str:
+        lines = ["Top performers:"]
+        for item in top_items:
+            lines.append(f"  [{item['id']}] conversion_rate={item.get('conversion_rate')}")
+        lines.append("Bottom performers:")
+        for item in bottom_items:
+            lines.append(f"  [{item['id']}] conversion_rate={item.get('conversion_rate')}")
+        return "\n".join(lines)
+```
+
+See `adapters/short_video.py` for a complete reference implementation.
+
+---
+
+## Experiment Modes
+
+| Mode | When to use | Description |
+|------|-------------|-------------|
+| `interleaved` | Tier 2 | Rotate variants across different items; maximises volume |
+| `paired` | Tier 1 | Generate two variants for the same item; cleaner causal inference |
+
+Tier 1 experiments (high-impact variables) should use `paired` mode to eliminate
+confounding factors introduced by item-level differences.
+
+---
+
+## Import Verification
+
+```bash
+python3 -c "from adaptive_iteration.core.experiment import Experiment; print('ok')"
+```
+
+---
+
+## Design Principles
+
+1. `core/` has **zero external deps** — pure Python stdlib only (`openai` in `hypothesis.py`
+   is lazy-imported and optional until you call `HypothesisEngine`).
+2. `DomainAdapter` is the **only** layer that touches external systems.
+3. `Ledger` is the **single source of truth** — append-only JSON, no database required.
+4. `HypothesisEngine` uses **structured JSON output** prompting so parsing is deterministic.

adaptive_iteration-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+adaptive_iteration/__init__.py,sha256=53mv6ma-Gxhi7wYTK_C9DF6XMe8lZEwqbCTweg_Eve4,581
+adaptive_iteration/adapters/__init__.py,sha256=Pxvt872_ZyCOn5f3IDIuKPyoaPSQ0894gV-W0XY7hGU,209
+adaptive_iteration/adapters/base.py,sha256=E0Q15j6vgGTYxIWwBnyJC4Ia4nLr0rH4qRmaCQjp64Y,2923
+adaptive_iteration/adapters/short_video.py,sha256=Cr6Q3sMjYRKX7UTbY7v6fZ4ekBVfZ18-fRiHngFx8ks,7205
+adaptive_iteration/core/__init__.py,sha256=Hbwg7CiFZee_Xy5AWXsK_HW2xM6E5jd8g43gGA2gOoo,68
+adaptive_iteration/core/analyzer.py,sha256=qoAEuyw3FGYYrICGksR-_7JNDXTOUarJQGj4DzY918c,5870
+adaptive_iteration/core/config.py,sha256=PGJPXo2Arzuv1BDqb8s2T6bTLe5MEBAvko1-QrueTvE,3719
+adaptive_iteration/core/experiment.py,sha256=W7h705JSKSW_2D2UBamO0LUnY39UsMPTsiCY5v6UiTU,4770
+adaptive_iteration/core/hypothesis.py,sha256=WgiYzQln13g4KNjQxBtPOr7ISBjgvJMixIUD6WgPDKA,7357
+adaptive_iteration/core/ledger.py,sha256=T6bFRP5ZewC8ad-Y7Lk2Ag65k0MGoxgT0rAphkP3hCY,4215
+adaptive_iteration-0.1.0.dist-info/METADATA,sha256=fVLoCCJf15_K3UYxcRxx8BshMhZSuRMVQ8Iyz3Ck3MI,5360
+adaptive_iteration-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+adaptive_iteration-0.1.0.dist-info/RECORD,,

adaptive_iteration-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any