methodic

Python client for the Chronicle experiment platform.

methodic is the supported integration path for both researchers (managing experiments, variations, and search) and runners (workers that pull configs, transition runs, upload assets). It is the same client menlo-park uses internally.

pip install methodic-research

from methodic import Chronicle

# Researcher: experiments, variations, search
with Chronicle(server_url="https://api.methodiclabs.ai", api_key="sk_user_...") as chronicle:
    exp = chronicle.experiments.create(
        hypothesis_summary="ripple effect on PDE solvers in 2D",
        config_yaml=open("experiment.yaml").read(),
    )
    exp.commit().variations.create(config_yaml=open("variation-2.yaml").read())

# Worker: run lifecycle + asset uploads
with Chronicle(server_url=..., api_key="sk_agent_...") as chronicle:
    run = chronicle.run(experiment_id, variation=1, run=1)
    run.start()
    run.upload_asset(asset_type="research_report", content={"summary": "..."})
    run.succeed()

API shape

Chronicle is the top-level client. Every operation lives on a namespace; resource handles are sugar for chained drill-downs.

Namespace	What it covers
chronicle.experiments, chronicle.variations	Experiments & variations — create, commit, conclude, retract, fork, distill, move, lineage; per-variation pre-registration + git
chronicle.runs (or chronicle.run(...))	Run lifecycle — start, heartbeat, succeed/fail, output uploads
chronicle.assets	Assets — inline + presigned upload, download, deprecate/invalidate, visibility + ACLs
chronicle.datasets	Datasets — upload/register/register_by_reference, provenance, link as input, load
chronicle.collections	Collections — topic groupings of experiments + assets
chronicle.tags	Tags — org keyword vocabulary on assets + experiments
chronicle.search	Search — Vertex-backed, ACL-filtered semantic search; history
chronicle.reports	Reports — render hypothesis/takeaways/research to PDF
chronicle.research_prompts	Research prompts — the brief that drives an experiment
chronicle.imports	Imports — bulk-import external PDFs into an org library
chronicle.errata	Errata — corrections/addenda on experiments, variations, assets
chronicle.publications	Publications — register external papers (DOI/BibTeX), cite as inputs
chronicle.pending, chronicle.activity	Attention & review — your action queue + scope event feed; asset approval
chronicle.api_keys	API keys — mint scoped keys, ceilings, rotate/revoke
chronicle.feedback	Feedback — product feedback + error reports
chronicle.me	scope discovery (scopes()) — resolve org/team ids (see Authentication)

Where to next

• Quickstart — install, authenticate, run the hello-world flow end-to-end.
• Claude Code & Desktop — drive Chronicle from Claude instead of Python: the chronicle plugin (skills + a zero-install MCP server) in Claude Code, and the Desktop .mcpb bundle.
• Guide — a page per namespace: experiments & variations, the run lifecycle, assets and datasets, search and discovery, reports, the attention/review loop, trainer integrations, and more.
• API reference — full namespace and handle reference, generated from docstrings.
• Design — protocol details and rationale.