methodic-research 0.1.2__tar.gz

methodic_research-0.1.2/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: methodic-research
+Version: 0.1.2
+Summary: Python client for the Chronicle experiment platform
+License-Expression: Apache-2.0
+Project-URL: Documentation, https://docs.methodiclabs.ai
+Project-URL: Source, https://github.com/methodic-research/methodic/tree/main/conductor
+Project-URL: Issues, https://github.com/methodic-research/methodic/issues
+Requires-Python: >=3.11
+Requires-Dist: requests
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-timeout; extra == "dev"
+Requires-Dist: requests-mock; extra == "dev"
+Provides-Extra: docs
+Requires-Dist: mkdocs>=1.6; extra == "docs"
+Requires-Dist: mkdocs-material>=9.5; extra == "docs"
+Requires-Dist: mkdocstrings[python]>=0.27; extra == "docs"
+Requires-Dist: ruff; extra == "docs"

methodic_research-0.1.2/README.md

@@ -0,0 +1,36 @@
+# methodic
+
+Python client for the [Chronicle](https://github.com/methodic-research/methodic) experiment platform.
+
+```bash
+pip install methodic-research
+```
+
+```python
+from methodic import Client
+
+client = Client(
+    server_url="https://chronicle.example.com",
+    experiment_id="...",
+    variation=1,
+    run=1,
+    api_key="sk_agent_...",
+)
+
+client.start_run()
+client.upload_asset(asset_type="research_report", content={"summary": "..."})
+client.succeed_run()
+client.close()
+```
+
+Full documentation: <https://docs.methodiclabs.ai>. Source for the protocol details (auth, run lifecycle, asset upload flow) lives in [`docs/design.md`](docs/design.md).
+
+## Releasing
+
+The package is published to PyPI by the `methodic-lib-publish.yml` workflow via PyPI trusted publishing (OIDC, no API token). To cut a release, bump `version` in `pyproject.toml` and push a matching tag:
+
+```bash
+git tag methodic-lib-v0.1.1 && git push --tags
+```
+
+The tag prefix is `methodic-lib-v*` rather than `methodic-v*` to keep the `methodic-*` namespace reserved in case the Chronicle platform itself is renamed to `methodic` later. The workflow validates that the tag version matches `pyproject.toml` before publishing.

methodic_research-0.1.2/pyproject.toml

@@ -0,0 +1,38 @@
+[build-system]
+requires = ["setuptools>=75.0", "wheel"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "methodic-research"
+version = "0.1.2"
+description = "Python client for the Chronicle experiment platform"
+requires-python = ">=3.11"
+license = "Apache-2.0"
+dependencies = [
+    "requests",
+]
+
+[project.urls]
+Documentation = "https://docs.methodiclabs.ai"
+Source = "https://github.com/methodic-research/methodic/tree/main/conductor"
+Issues = "https://github.com/methodic-research/methodic/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0",
+    "pytest-timeout",
+    "requests-mock",
+]
+docs = [
+    "mkdocs>=1.6",
+    "mkdocs-material>=9.5",
+    "mkdocstrings[python]>=0.27",
+    "ruff",
+]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+timeout = 30

methodic_research-0.1.2/setup.cfg

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

methodic_research-0.1.2/src/methodic/__init__.py

@@ -0,0 +1,79 @@
+"""Public API for the methodic SDK."""
+
+from methodic.assets import AssetsAPI, AssetUploadInfo
+from methodic.chronicle import Chronicle
+from methodic.errors import (
+    APIError,
+    AuthenticationError,
+    BadRequestError,
+    ChronicleError,
+    ConflictError,
+    NotFoundError,
+    PermissionDeniedError,
+    ServerError,
+)
+from methodic.experiments import Experiment, ExperimentsAPI
+from methodic.reports import Report, ReportsAPI
+from methodic.runs import Run, RunsAPI
+from methodic.search import SearchAPI
+from methodic.types import (
+    CreateExperimentResponse,
+    Experiment as ExperimentData,
+    ExperimentDetail,
+    ExperimentListPage,
+    ExperimentSummary,
+    GitBranch,
+    GitStatus,
+    GitToken,
+    LineageResponse,
+    SearchFilters,
+    SearchResponse,
+    SearchResult,
+    UpstreamRetraction,
+    UpstreamRetractionsResponse,
+    Variation as VariationData,
+    VariationSummary,
+)
+from methodic.upload_tracker import PendingUpload, UploadTracker
+from methodic.variations import Variation, VariationsAPI
+
+__all__ = [
+    "APIError",
+    "AssetUploadInfo",
+    "AssetsAPI",
+    "AuthenticationError",
+    "BadRequestError",
+    "Chronicle",
+    "ChronicleError",
+    "ConflictError",
+    "CreateExperimentResponse",
+    "Experiment",
+    "ExperimentData",
+    "ExperimentDetail",
+    "ExperimentListPage",
+    "ExperimentSummary",
+    "ExperimentsAPI",
+    "GitBranch",
+    "GitStatus",
+    "GitToken",
+    "LineageResponse",
+    "NotFoundError",
+    "PendingUpload",
+    "PermissionDeniedError",
+    "Report",
+    "ReportsAPI",
+    "Run",
+    "RunsAPI",
+    "SearchAPI",
+    "SearchFilters",
+    "SearchResponse",
+    "SearchResult",
+    "ServerError",
+    "UploadTracker",
+    "UpstreamRetraction",
+    "UpstreamRetractionsResponse",
+    "Variation",
+    "VariationData",
+    "VariationSummary",
+    "VariationsAPI",
+]

methodic_research-0.1.2/src/methodic/assets.py

@@ -0,0 +1,143 @@
+"""Asset primitives.
+
+The full researcher-facing AssetsAPI lands later (deprecate, invalidate,
+list, search-tied operations). This module currently exposes the low-level
+operations every other namespace needs: create-with-presigned-URLs, upload
+components, finalize, fetch metadata, presign, stream download.
+"""
+
+from __future__ import annotations
+
+import logging
+from dataclasses import dataclass
+from pathlib import Path
+from typing import Any
+
+from methodic.transport import Transport
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass(frozen=True)
+class AssetUploadInfo:
+    """Result of `AssetsAPI.create_with_presigned`: where to put each component."""
+
+    asset_id: str
+    asset_uri: str
+    upload_urls: dict[str, str]  # component name → presigned PUT URL
+
+
+class AssetsAPI:
+    """Asset operations.
+
+    Output-of linking (which experiment/variation/run produced this asset) is
+    passed explicitly by callers — `Run` populates it from its bound context,
+    while researcher-level uploads pass it directly or omit it for shared assets.
+    """
+
+    def __init__(self, transport: Transport) -> None:
+        self._t = transport
+
+    def create_inline(
+        self,
+        *,
+        asset_type: str,
+        content: Any,
+        name: str | None = None,
+        content_type: str = "application/json",
+        output_of: dict[str, Any] | None = None,
+        asset_config: dict[str, Any] | None = None,
+    ) -> dict[str, Any]:
+        """Upload a small inline asset. Chronicle auto-finalizes."""
+        payload: dict[str, Any] = {
+            "name": name or asset_type,
+            "asset_type": asset_type,
+            "content_type": content_type,
+            "content": content,
+        }
+        if output_of is not None:
+            payload["output_of"] = output_of
+        if asset_config is not None:
+            payload["asset_config"] = asset_config
+        logger.info("Creating inline %s asset", asset_type)
+        return self._t.post("/assets", json=payload)
+
+    def create_with_presigned(
+        self,
+        *,
+        asset_type: str,
+        components: list[str],
+        name: str | None = None,
+        content_type: str = "application/octet-stream",
+        output_of: dict[str, Any] | None = None,
+    ) -> AssetUploadInfo:
+        """Register a new asset and get presigned PUT URLs for each component."""
+        payload: dict[str, Any] = {
+            "name": name or asset_type,
+            "asset_type": asset_type,
+            "presign": True,
+            "components": components,
+            "content_type": content_type,
+        }
+        if output_of is not None:
+            payload["output_of"] = output_of
+        data = self._t.post("/assets", json=payload)
+        asset = data["asset"]
+        upload_urls = {
+            (u.get("component") or "default"): u["url"] for u in (data.get("upload_urls") or [])
+        }
+        return AssetUploadInfo(
+            asset_id=asset["id"],
+            asset_uri=asset["uri"],
+            upload_urls=upload_urls,
+        )
+
+    def upload_component(
+        self, upload_url: str, local_path: Path, content_type: str
+    ) -> None:
+        """PUT one component to its presigned URL."""
+        logger.debug("Uploading %s via presigned URL", local_path.name)
+        with open(local_path, "rb") as f:
+            self._t.put_to_presigned(upload_url, data=f, content_type=content_type)
+
+    def finalize(self, asset_id: str) -> None:
+        """Mark a presigned-upload asset as ready (immutable) once all components are up."""
+        self._t.put(f"/assets/{asset_id}/finalize")
+
+    def get(self, asset_id: str, *, include_presigned: bool = False) -> dict[str, Any]:
+        """Fetch asset metadata. With `include_presigned=True`, includes read URLs."""
+        params = {"include_presigned": "true"} if include_presigned else None
+        return self._t.get(f"/assets/{asset_id}", params=params)
+
+    def presign(
+        self,
+        asset_id: str,
+        *,
+        operation: str = "read",
+        components: list[str] | None = None,
+    ) -> dict[str, Any]:
+        """Request presigned URLs for an asset's components."""
+        payload: dict[str, Any] = {"operation": operation}
+        if components:
+            payload["components"] = components
+        resp = self._t.post(f"/assets/{asset_id}/presign", json=payload)
+        return resp.get("presigned_urls", {})
+
+    def download(self, asset_id: str, local_dir: Path) -> Path:
+        """Download all components of an asset to a local directory."""
+        asset = self.get(asset_id, include_presigned=True)
+        local_dir.mkdir(parents=True, exist_ok=True)
+
+        for component, url_info in asset.get("presigned_urls", {}).items():
+            local_path = local_dir / component
+            local_path.parent.mkdir(parents=True, exist_ok=True)
+            logger.info("Downloading %s → %s", component, local_path)
+            resp = self._t.get_streaming(url_info["url"])
+            try:
+                with open(local_path, "wb") as f:
+                    for chunk in resp.iter_content(chunk_size=8192):
+                        f.write(chunk)
+            finally:
+                resp.close()
+
+        return local_dir

methodic_research-0.1.2/src/methodic/chronicle.py

@@ -0,0 +1,88 @@
+"""Top-level entry point for the methodic SDK.
+
+`Chronicle` owns the HTTP transport and a shared upload thread pool, then
+wires up every namespace (`runs`, `assets`, …; experiments/variations/search
+land in subsequent phases). Most users construct one `Chronicle` per
+process and reuse it across runs and researcher operations.
+"""
+
+from __future__ import annotations
+
+import logging
+from concurrent.futures import ThreadPoolExecutor
+from types import TracebackType
+
+from methodic.assets import AssetsAPI
+from methodic.experiments import Experiment, ExperimentsAPI
+from methodic.reports import ReportsAPI
+from methodic.runs import Run, RunsAPI
+from methodic.search import SearchAPI
+from methodic.transport import Transport
+from methodic.variations import Variation, VariationsAPI
+
+logger = logging.getLogger(__name__)
+
+
+class Chronicle:
+    """Client for the Chronicle REST API.
+
+    Construct once with the server URL + API key, then call into namespaces:
+
+        chronicle = Chronicle(server_url="https://api.methodiclabs.ai", api_key="sk_...")
+
+        # Researcher
+        exp = chronicle.experiments.create(hypothesis_summary="...", config_yaml="...")
+        exp.commit().variations.create(config_yaml="...")
+
+        # Worker
+        run = chronicle.run(experiment_id, variation, run_idx)
+        run.start().heartbeat()
+        run.upload_asset(asset_type="research_report", content={"summary": "..."})
+        run.succeed()
+
+    Use as a context manager to guarantee the executor and HTTP session are closed.
+    """
+
+    def __init__(
+        self,
+        server_url: str,
+        api_key: str,
+        timeout: int = 30,
+        max_upload_workers: int = 2,
+    ) -> None:
+        self._transport = Transport(server_url, api_key, timeout)
+        self._executor = ThreadPoolExecutor(max_workers=max_upload_workers)
+        self.assets = AssetsAPI(self._transport)
+        self.runs = RunsAPI(self._transport, self.assets, self._executor)
+        self.variations = VariationsAPI(self._transport, self)
+        self.experiments = ExperimentsAPI(self._transport, self)
+        self.search = SearchAPI(self._transport, self)
+        self.reports = ReportsAPI(self._transport, self)
+
+    def run(self, experiment_id: str, variation: int, run: int) -> Run:
+        """Construct a `Run` resource handle bound to one (experiment, variation, run)."""
+        return Run(self.runs, experiment_id, variation, run)
+
+    def experiment(self, experiment_id: str) -> Experiment:
+        """Get a handle for an existing experiment by id (lazy — no fetch until accessed)."""
+        return Experiment(self, experiment_id)
+
+    def variation(self, experiment_id: str, variation: int) -> Variation:
+        """Get a handle for an existing variation by (experiment_id, variation)."""
+        return Variation(self, experiment_id, variation)
+
+    def close(self) -> None:
+        """Shut down the upload pool and HTTP session. Idempotent."""
+        self._executor.shutdown(wait=True)
+        self._transport.close()
+
+    def __enter__(self) -> Chronicle:
+        return self
+
+    def __exit__(
+        self,
+        exc_type: type[BaseException] | None,
+        exc: BaseException | None,
+        tb: TracebackType | None,
+    ) -> None:
+        self.close()

methodic_research-0.1.2/src/methodic/errors.py

@@ -0,0 +1,70 @@
+"""Exception hierarchy for the methodic SDK."""
+
+from __future__ import annotations
+
+import requests
+
+
+class ChronicleError(Exception):
+    """Base class for every error raised by the methodic client."""
+
+
+class APIError(ChronicleError):
+    """HTTP error from the Chronicle API."""
+
+    def __init__(self, status_code: int, message: str, response: requests.Response | None = None):
+        self.status_code = status_code
+        self.message = message
+        self.response = response
+        super().__init__(f"{status_code}: {message}")
+
+
+class AuthenticationError(APIError):
+    """401 — missing or invalid credentials."""
+
+
+class PermissionDeniedError(APIError):
+    """403 — caller lacks the required ACL grants."""
+
+
+class NotFoundError(APIError):
+    """404 — resource does not exist or is hidden by RBAC."""
+
+
+class BadRequestError(APIError):
+    """400/422 — malformed request body or invalid arguments."""
+
+
+class ConflictError(APIError):
+    """409 — state conflict (e.g., commit on already-committed experiment)."""
+
+
+class ServerError(APIError):
+    """5xx — Chronicle is unreachable, misconfigured, or buggy."""
+
+
+def raise_for_response(resp: requests.Response) -> None:
+    """Translate a non-2xx HTTP response into the right `APIError` subclass."""
+    if resp.ok:
+        return
+
+    body = resp.text or ""
+    status = resp.status_code
+
+    cls: type[APIError]
+    if status == 400 or status == 422:
+        cls = BadRequestError
+    elif status == 401:
+        cls = AuthenticationError
+    elif status == 403:
+        cls = PermissionDeniedError
+    elif status == 404:
+        cls = NotFoundError
+    elif status == 409:
+        cls = ConflictError
+    elif 500 <= status < 600:
+        cls = ServerError
+    else:
+        cls = APIError
+
+    raise cls(status, body, resp)