adaptive-iteration 0.1.0__tar.gz

adaptive_iteration-0.1.0/.gitignore

@@ -0,0 +1,47 @@
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.so
+.Python
+build/
+dist/
+*.egg-info/
+.eggs/
+*.egg
+
+# Virtual environments
+.venv/
+venv/
+env/
+ENV/
+
+# Pytest
+.pytest_cache/
+.coverage
+htmlcov/
+
+# Data / ledger files
+data/
+*.json
+*.tsv
+*.csv
+
+# Secrets
+.env
+*.env
+secrets/
+*-key
+*-token
+*_key
+*_token
+
+# macOS
+.DS_Store
+.AppleDouble
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo

adaptive_iteration-0.1.0/PKG-INFO

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

@@ -0,0 +1,154 @@
+# 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/__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-0.1.0/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-0.1.0/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-0.1.0/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-0.1.0/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-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"]