Metadata-Version: 2.4
Name: talocode-experimentlane
Version: 0.1.1
Summary: Evidence-driven experimentation engine for AI agents — record experiments, compare against baselines, change exactly one variable at a time
Author: Talocode
License-Expression: MIT
License-File: LICENSE
Keywords: ab-testing,agent,ai-agents,cli,content,experiment,mcp,metrics,receipts,sdk,talocode
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Requires-Python: >=3.8
Description-Content-Type: text/markdown

# ExperimentLane

An evidence-driven experimentation engine for AI agents. Record experiments, compare them against baselines, and get a deterministic decision about what to change next — one variable at a time.

The Python package mirrors the TypeScript implementation (`@talocode/experimentlane`) 1:1.

## What is it

ExperimentLane tracks content and agent experiments as **receipts**: a baseline, a run, and the platform-exposed metrics that come back. It compares them, names a winner, picks the strongest and weakest signals, and tells the agent exactly what to change next while everything else stays constant.

## Why it exists

Most agents ship a variation, see a number, and guess. That is how B-tests quietly become A/B/C/D tests and nothing is ever attributable.

ExperimentLane encodes the discipline most agents are missing: **change exactly one independent variable at a time**. It is a local, deterministic, no-frills engine any agent can embed, so experiments stay honest, small, and comparable.

Open engine first. The hosted power can come later — the same schema is shaped for the Talocode API surface.

## Install

```bash
pip install talocode-experimentlane
```

Python 3.8+, no runtime dependencies.

## Quickstart

```python
from talocode_experimentlane import ExperimentLane, JsonStore

lane = ExperimentLane(JsonStore(".experimentlane"))
lane.init()

# 1. Define a lane for a platform's exposed metrics
shorts = lane.create_lane(name="youtube-shorts", platform="youtube_short")

# 2. Record a baseline (the control asset's platform-exposed metrics)
base = lane.create_baseline(
    lane_id=shorts["id"],
    metrics={"views": 480, "avg_view_percent": 75, "shares": 10, "subscribers": 2},
)

# 3. Create the experiment — exactly one variable changes
asset = lane.create_asset(lane_id=shorts["id"], title="reliability-short-2")
exp = lane.create_experiment(
    lane_id=shorts["id"], asset_id=asset["id"], baseline_id=base["id"], variable="hook"
)

# 4. Record the receipt after the run
lane.add_receipt(
    experiment_id=exp["id"],
    metrics={"views": 624, "avg_view_percent": 87, "shares": 14, "subscribers": 3},
)

# 5. Compare and get one deterministic decision
result = lane.compare(experiment_id=exp["id"])
print(result["comparison"]["winner"])      # "experiment"
print(result["decision"]["line"]["nextExperiment"])  # "change only <weakest signal>"
print(result["decision"]["line"]["everythingElse"])  # "hold constant"
```

Canonical import: `from talocode_experimentlane import ExperimentLane, JsonStore`.

## Auth / env

The local store needs no API key. Optional environment variable:

- `EXPERIMENTLANE_DIR` — override the default data directory (default `.experimentlane`).

## API surface

Everything is comparable-metrics only — absent metrics are "unavailable", never a failure.

| Method | Purpose |
|--------|---------|
| `create_lane` | Define a platform and its metric priority |
| `create_asset` | A piece of content or an agent run |
| `create_baseline` | The control — an asset snapshot or explicit metrics |
| `create_experiment` | An assignment changing exactly **one** variable |
| `add_receipt` | The platform-exposed metrics that came back |
| `compare` | Computes deltas, names winner, picks strongest/weakest signals |
| `next` | Recommends the next single variable to change |
| `validate_next` | Guardrail: reject proposals that change 2+ variables |
| `history` | Full audit trail per experiment |
| `lineage_of` | The reuse lineage of an asset back to its primary proof |

### Platform schemas

Platforms (`youtube_short`, `tiktok`, `instagram_reel`, `x_post`, `generic`) map their exposed metrics. `shares_per_view` is derived from views + shares when both are present. A receipt may only contain metrics listed for its lane platform — unknown keys raise a clear error.

### Guardrail codes

| Code | Meaning |
|------|---------|
| `EXPERIMENT_OK` | Exactly one independent variable changed |
| `EXPERIMENT_INVALID` | 2+ independent variables changed — reject |

### CLI

```bash
experimentlane lane create --name my-shorts --platform youtube_short
experimentlane receipt add --experiment <id> --views 624 --shares 14
experimentlane compare --experiment <id>
experimentlane next --experiment <id> --propose hook,duration   # guardrail check
```

Data lives in `.experimentlane` (override with `EXPERIMENTLANE_DIR`).

## Related packages

Sibling installs for the Talocode ecosystem:

| Package | Install |
|---------|---------|
| [StackLane](https://github.com/talocode/stacklane) | `pip install talocode` |
| [Tera](https://github.com/talocode/tera) | `pip install talocode-tera` |
| [Codra](https://github.com/talocode/codra) | `pip install talocode-codra` |
| [DocuLane](https://github.com/talocode/doculane) | `pip install talocode-doculane` |
| [XSearchLane](https://github.com/talocode/xsearchlane) | `npm i @talocode/xsearchlane` |

## Talocode ecosystem

| Product | Description |
|---------|--------------|
| [ExperimentLane](https://github.com/talocode/experimentlane) | **(this package)** — evidence-driven experiment engine for agents |
| [Tera](https://github.com/talocode/tera) | Capability API under Talocode Cloud |
| [Codra](https://github.com/talocode/codra) | Coding agent / skills runtime |
| [StackLane](https://github.com/talocode/stacklane) | Cloud backend: projects, API keys, credits, billing |
| [SearchLane](https://github.com/talocode/searchlane) | Search API product |
| [GateLane](https://github.com/talocode/gatelane) | Policy gates |
| [ContextLane](https://github.com/talocode/contextlane) | Context management |
| [ScreenLane](https://github.com/talocode/screenlane) | Screen capture pipeline |
| [MemoryLane](https://github.com/talocode/memorylane) | Agent memory |
| [Tradia](https://github.com/talocode/tradia) | Trading agents |
| [DevTool](https://github.com/talocode/devtool) | Developer tooling |
| [XProLane](https://github.com/talocode/xprolane) | X advanced tools |
| [XSearchLane](https://github.com/talocode/xsearchlane) | X realtime search |
| [Agent Browser](https://github.com/talocode/agent-browser) | Browser control |
| [InvoiceLane](https://github.com/talocode/invoicelane) | Invoicing |
| [GeoLane](https://github.com/talocode/geolane) | Geolocation |
| [ClipLoop](https://github.com/talocode/cliploop) | Clip builder |
| [DocuLane](https://github.com/talocode/doculane) | Office document tools for agents |

More: [github.com/talocode](https://github.com/talocode) · [talocode.site](https://talocode.site) · [docs.talocode.site](https://docs.talocode.site)

## License

MIT © Talocode.