replicatescience 0.1.0__tar.gz

replicatescience-0.1.0/.gitignore

@@ -0,0 +1,15 @@
+__pycache__/
+*.py[cod]
+*$py.class
+dist/
+build/
+*.egg-info/
+*.egg
+.eggs/
+.tox/
+.venv/
+venv/
+*.so
+.mypy_cache/
+.pytest_cache/
+.ruff_cache/

replicatescience-0.1.0/CLAUDE.md

@@ -0,0 +1,36 @@
+# ReplicateScience Python SDK
+
+## What This Is
+Python SDK + CLI for the ReplicateScience API. Wraps https://replicatescience.com/api/v1/ endpoints. Published to PyPI as `replicatescience`.
+
+**PyPI:** https://pypi.org/project/replicatescience/
+**GitHub:** https://github.com/ShuhanCS/replicatescience-python
+**API docs:** https://replicatescience.com/developers
+
+## Structure
+- `src/replicatescience/` — package source (src layout)
+- `src/replicatescience/__init__.py` — top-level convenience functions (search, get, diff, save, load)
+- `src/replicatescience/client.py` — HTTP client using httpx
+- `src/replicatescience/models.py` — dataclass models matching API types
+- `src/replicatescience/export.py` — YAML/JSON file export/import
+- `src/replicatescience/cli.py` — Click CLI (`rs` command)
+
+## Key Decisions
+- Models match `src/types/api.ts` from the main replicatescience repo (snake_case)
+- Uses httpx (not requests) for modern async-ready HTTP
+- src layout for clean packaging
+- Hatchling build backend (fast, modern)
+- CLI entry point: `rs` (registered in pyproject.toml)
+
+## Development
+```bash
+pip install -e ".[dev]"   # editable install
+python -m pytest tests/   # run tests
+python -m build           # build dist
+twine upload dist/*       # publish to PyPI
+```
+
+## Rules
+- Version in both `pyproject.toml` and `__init__.py` — keep in sync
+- Models must stay in sync with the main replicatescience API types
+- Never store or log API keys

replicatescience-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ConductScience Inc.
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

replicatescience-0.1.0/PKG-INFO

@@ -0,0 +1,96 @@
+Metadata-Version: 2.4
+Name: replicatescience
+Version: 0.1.0
+Summary: Python SDK for ReplicateScience — programmable protocol library for reproducible science
+Project-URL: Homepage, https://replicatescience.com
+Project-URL: Documentation, https://replicatescience.com/developers
+Project-URL: Repository, https://github.com/ShuhanCS/replicatescience-python
+Project-URL: Issues, https://github.com/ShuhanCS/replicatescience-python/issues
+Author-email: ReplicateScience <support@replicatescience.com>
+License-Expression: MIT
+License-File: LICENSE
+Keywords: biology,equipment,protocols,reproducibility,science
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+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: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Classifier: Topic :: Scientific/Engineering
+Classifier: Topic :: Scientific/Engineering :: Bio-Informatics
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: pyyaml>=6.0
+Description-Content-Type: text/markdown
+
+# ReplicateScience Python SDK
+
+Programmable protocol library for reproducible science. Search, compare, and export experimental protocols extracted from published papers.
+
+## Installation
+
+```bash
+pip install replicatescience
+```
+
+## Quick Start
+
+```python
+import replicatescience as rs
+
+# Configure your API key (or set RS_API_KEY env var)
+rs.configure(api_key="rs_live_YOUR_KEY")
+
+# Search protocols by keyword + species
+results = rs.search("fear conditioning", species="mouse")
+for p in results.protocols:
+    print(f"{p.slug}: {p.name} ({p.step_count} steps)")
+
+# Get full protocol detail
+protocol = rs.get("smith-fear-conditioning-2024")
+
+# Compare two protocols
+diff = rs.diff(
+    rs.get("smith-fear-conditioning-2024"),
+    rs.get("jones-fear-conditioning-2023"),
+)
+print(diff.summary)
+print(diff.to_markdown())
+
+# Export to YAML
+rs.save(protocol, "protocols/fear-conditioning.yaml")
+```
+
+## CLI
+
+```bash
+# Search from terminal
+rs search "pcr" --species mouse --limit 5
+
+# Get a protocol
+rs get smith-fear-conditioning-2024 --format yaml > protocol.yaml
+
+# Diff two protocols
+rs diff smith-2024 jones-2023
+```
+
+## API Key
+
+Get your free API key at [replicatescience.com/developers](https://replicatescience.com/developers).
+
+| Plan | Requests/Day | Exports/Day |
+|------|-------------|-------------|
+| Free | 100 | 10 |
+| Pro | 5,000 | Unlimited |
+| Institutional | 50,000 | Unlimited |
+
+## Links
+
+- [Documentation](https://replicatescience.com/developers)
+- [API Reference (OpenAPI)](https://replicatescience.com/api/v1/openapi.json)
+- [GitHub](https://github.com/ShuhanCS/replicatescience-python)

replicatescience-0.1.0/README.md

@@ -0,0 +1,66 @@
+# ReplicateScience Python SDK
+
+Programmable protocol library for reproducible science. Search, compare, and export experimental protocols extracted from published papers.
+
+## Installation
+
+```bash
+pip install replicatescience
+```
+
+## Quick Start
+
+```python
+import replicatescience as rs
+
+# Configure your API key (or set RS_API_KEY env var)
+rs.configure(api_key="rs_live_YOUR_KEY")
+
+# Search protocols by keyword + species
+results = rs.search("fear conditioning", species="mouse")
+for p in results.protocols:
+    print(f"{p.slug}: {p.name} ({p.step_count} steps)")
+
+# Get full protocol detail
+protocol = rs.get("smith-fear-conditioning-2024")
+
+# Compare two protocols
+diff = rs.diff(
+    rs.get("smith-fear-conditioning-2024"),
+    rs.get("jones-fear-conditioning-2023"),
+)
+print(diff.summary)
+print(diff.to_markdown())
+
+# Export to YAML
+rs.save(protocol, "protocols/fear-conditioning.yaml")
+```
+
+## CLI
+
+```bash
+# Search from terminal
+rs search "pcr" --species mouse --limit 5
+
+# Get a protocol
+rs get smith-fear-conditioning-2024 --format yaml > protocol.yaml
+
+# Diff two protocols
+rs diff smith-2024 jones-2023
+```
+
+## API Key
+
+Get your free API key at [replicatescience.com/developers](https://replicatescience.com/developers).
+
+| Plan | Requests/Day | Exports/Day |
+|------|-------------|-------------|
+| Free | 100 | 10 |
+| Pro | 5,000 | Unlimited |
+| Institutional | 50,000 | Unlimited |
+
+## Links
+
+- [Documentation](https://replicatescience.com/developers)
+- [API Reference (OpenAPI)](https://replicatescience.com/api/v1/openapi.json)
+- [GitHub](https://github.com/ShuhanCS/replicatescience-python)

replicatescience-0.1.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "replicatescience"
+version = "0.1.0"
+description = "Python SDK for ReplicateScience — programmable protocol library for reproducible science"
+readme = "README.md"
+license = "MIT"
+requires-python = ">=3.9"
+authors = [
+    { name = "ReplicateScience", email = "support@replicatescience.com" },
+]
+keywords = ["science", "protocols", "reproducibility", "biology", "equipment"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.9",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+    "Programming Language :: Python :: 3.14",
+    "Topic :: Scientific/Engineering",
+    "Topic :: Scientific/Engineering :: Bio-Informatics",
+]
+dependencies = [
+    "httpx>=0.25.0",
+    "click>=8.0",
+    "pyyaml>=6.0",
+]
+
+[project.urls]
+Homepage = "https://replicatescience.com"
+Documentation = "https://replicatescience.com/developers"
+Repository = "https://github.com/ShuhanCS/replicatescience-python"
+Issues = "https://github.com/ShuhanCS/replicatescience-python/issues"
+
+[project.scripts]
+rs = "replicatescience.cli:main"

replicatescience-0.1.0/src/replicatescience/__init__.py

@@ -0,0 +1,135 @@
+"""ReplicateScience Python SDK — programmable protocol library for reproducible science."""
+
+from replicatescience.client import Client
+from replicatescience.models import (
+    Equipment,
+    EquipmentDetail,
+    Pagination,
+    Protocol,
+    ProtocolDetail,
+    ProtocolDiff,
+    RateLimit,
+    SearchResult,
+    SearchResults,
+)
+
+__version__ = "0.1.0"
+__all__ = [
+    "configure",
+    "search",
+    "get",
+    "diff",
+    "save",
+    "load",
+    "get_equipment",
+    "search_equipment",
+    "me",
+    "Client",
+    "Protocol",
+    "ProtocolDetail",
+    "ProtocolDiff",
+    "Equipment",
+    "EquipmentDetail",
+    "SearchResult",
+    "SearchResults",
+    "Pagination",
+    "RateLimit",
+]
+
+_default_client: Client | None = None
+
+
+def _get_client() -> Client:
+    global _default_client
+    if _default_client is None:
+        _default_client = Client()
+    return _default_client
+
+
+def configure(
+    api_key: str | None = None,
+    base_url: str | None = None,
+) -> None:
+    """Configure the default client.
+
+    Args:
+        api_key: Your ReplicateScience API key (rs_live_...).
+            Falls back to RS_API_KEY environment variable.
+        base_url: API base URL. Defaults to https://replicatescience.com.
+    """
+    global _default_client
+    _default_client = Client(api_key=api_key, base_url=base_url)
+
+
+def search(
+    query: str,
+    *,
+    species: str | None = None,
+    strain: str | None = None,
+    type: str | None = None,
+    year_min: int | None = None,
+    year_max: int | None = None,
+    sort: str | None = None,
+    page: int = 1,
+    limit: int = 20,
+) -> SearchResults:
+    """Search protocols by keyword and filters."""
+    return _get_client().search_protocols(
+        query,
+        species=species,
+        strain=strain,
+        type=type,
+        year_min=year_min,
+        year_max=year_max,
+        sort=sort,
+        page=page,
+        limit=limit,
+    )
+
+
+def get(slug: str) -> ProtocolDetail:
+    """Get full protocol detail by slug."""
+    return _get_client().get_protocol(slug)
+
+
+def diff(a: ProtocolDetail, b: ProtocolDetail) -> ProtocolDiff:
+    """Compare two protocols and return their differences."""
+    return ProtocolDiff.compute(a, b)
+
+
+def save(protocol: ProtocolDetail, path: str) -> None:
+    """Export a protocol to a YAML or JSON file."""
+    from replicatescience.export import save_protocol
+
+    save_protocol(protocol, path)
+
+
+def load(path: str) -> ProtocolDetail:
+    """Load a protocol from a YAML or JSON file."""
+    from replicatescience.export import load_protocol
+
+    return load_protocol(path)
+
+
+def get_equipment(slug: str) -> EquipmentDetail:
+    """Get full equipment detail by slug."""
+    return _get_client().get_equipment(slug)
+
+
+def search_equipment(
+    query: str | None = None,
+    *,
+    category: str | None = None,
+    manufacturer: str | None = None,
+    page: int = 1,
+    limit: int = 20,
+) -> SearchResults:
+    """Search equipment."""
+    return _get_client().search_equipment(
+        query, category=category, manufacturer=manufacturer, page=page, limit=limit
+    )
+
+
+def me() -> dict:
+    """Get API key info and rate limits."""
+    return _get_client().me()

replicatescience-0.1.0/src/replicatescience/cli.py

@@ -0,0 +1,149 @@
+"""CLI interface for ReplicateScience."""
+
+from __future__ import annotations
+
+import json
+import sys
+
+import click
+import yaml
+
+import replicatescience as rs
+
+
+@click.group()
+@click.version_option(rs.__version__, prog_name="replicatescience")
+@click.option("--api-key", envvar="RS_API_KEY", help="API key (or set RS_API_KEY)")
+def main(api_key: str | None):
+    """ReplicateScience CLI — search, compare, and export scientific protocols."""
+    if api_key:
+        rs.configure(api_key=api_key)
+
+
+@main.command()
+@click.argument("query")
+@click.option("--species", help="Filter by species")
+@click.option("--strain", help="Filter by strain")
+@click.option("--type", "exp_type", help="Filter by experiment type")
+@click.option("--limit", default=20, help="Max results", show_default=True)
+@click.option("--page", default=1, help="Page number", show_default=True)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def search(
+    query: str,
+    species: str | None,
+    strain: str | None,
+    exp_type: str | None,
+    limit: int,
+    page: int,
+    as_json: bool,
+):
+    """Search protocols by keyword."""
+    results = rs.search(
+        query, species=species, strain=strain, type=exp_type, limit=limit, page=page
+    )
+
+    if as_json:
+        click.echo(json.dumps([p.to_dict() for p in results.protocols], indent=2))
+        return
+
+    if not results.protocols:
+        click.echo("No protocols found.")
+        return
+
+    for p in results.protocols:
+        click.echo(f"  {p.slug}")
+        click.echo(f"    {p.name}")
+        meta = []
+        if p.species:
+            meta.append(p.species)
+        if p.strain:
+            meta.append(p.strain)
+        meta.append(f"{p.step_count} steps")
+        meta.append(f"{p.equipment_count} equipment")
+        click.echo(f"    {' | '.join(meta)}")
+        click.echo()
+
+    if results.pagination:
+        pg = results.pagination
+        click.echo(f"Page {pg.page} of {(pg.total + pg.limit - 1) // pg.limit} ({pg.total} total)")
+
+
+@main.command("get")
+@click.argument("slug")
+@click.option("--format", "fmt", type=click.Choice(["text", "json", "yaml"]), default="text", show_default=True)
+def get_protocol(slug: str, fmt: str):
+    """Get full protocol detail by slug."""
+    protocol = rs.get(slug)
+
+    if fmt == "json":
+        click.echo(json.dumps(protocol.to_dict(), indent=2))
+    elif fmt == "yaml":
+        click.echo(yaml.dump(protocol.to_dict(), default_flow_style=False, sort_keys=False))
+    else:
+        click.echo(f"# {protocol.name}")
+        click.echo(f"Paper: {protocol.paper.title}")
+        if protocol.paper.doi:
+            click.echo(f"DOI: {protocol.paper.doi}")
+        click.echo(f"Species: {protocol.species or 'N/A'} | Strain: {protocol.strain or 'N/A'}")
+        click.echo(f"Tags: {', '.join(protocol.tags) if protocol.tags else 'None'}")
+        click.echo()
+
+        if protocol.steps:
+            click.echo("## Steps")
+            for step in protocol.steps:
+                title = f" — {step.title}" if step.title else ""
+                duration = f" ({step.duration})" if step.duration else ""
+                click.echo(f"  {step.number}. {step.description[:100]}{title}{duration}")
+            click.echo()
+
+        if protocol.equipment:
+            click.echo("## Equipment")
+            for eq in protocol.equipment:
+                mfr = f" ({eq.manufacturer})" if eq.manufacturer else ""
+                click.echo(f"  - {eq.name}{mfr}")
+
+
+@main.command()
+@click.argument("slug_a")
+@click.argument("slug_b")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def diff(slug_a: str, slug_b: str, as_json: bool):
+    """Compare two protocols."""
+    # Load from file or API
+    a = _load_or_fetch(slug_a)
+    b = _load_or_fetch(slug_b)
+
+    result = rs.diff(a, b)
+
+    if as_json:
+        out = {
+            "protocol_a": result.protocol_a,
+            "protocol_b": result.protocol_b,
+            "summary": result.summary,
+            "changes": [
+                {"field": c.field, "label": c.label, "old": c.old, "new": c.new}
+                for c in result.changes
+            ],
+        }
+        click.echo(json.dumps(out, indent=2))
+    else:
+        click.echo(result.to_markdown())
+
+
+def _load_or_fetch(slug_or_path: str) -> rs.ProtocolDetail:
+    """Load a protocol from a local file or fetch by slug."""
+    if slug_or_path.endswith((".yaml", ".yml", ".json")):
+        return rs.load(slug_or_path)
+    return rs.get(slug_or_path)
+
+
+@main.command()
+def whoami():
+    """Show API key info and rate limits."""
+    info = rs.me()
+    click.echo(f"Email: {info.get('email', 'N/A')}")
+    click.echo(f"Name: {info.get('name', 'N/A')}")
+    click.echo(f"Tier: {info.get('tier', 'N/A')}")
+    rl = info.get("rate_limit", {})
+    click.echo(f"Rate limit: {rl.get('remaining', '?')}/{rl.get('limit', '?')} remaining")
+    click.echo(f"Resets at: {rl.get('resets_at', 'N/A')}")

replicatescience-0.1.0/src/replicatescience/client.py

@@ -0,0 +1,223 @@
+"""HTTP client for the ReplicateScience API."""
+
+from __future__ import annotations
+
+import os
+
+import httpx
+
+from replicatescience.models import (
+    Equipment,
+    EquipmentDetail,
+    Pagination,
+    Protocol,
+    ProtocolDetail,
+    RateLimit,
+    SearchResult,
+    SearchResults,
+)
+
+DEFAULT_BASE_URL = "https://replicatescience.com"
+
+
+class ReplicateScienceError(Exception):
+    """Base exception for ReplicateScience API errors."""
+
+    def __init__(self, message: str, status_code: int | None = None):
+        super().__init__(message)
+        self.status_code = status_code
+
+
+class AuthenticationError(ReplicateScienceError):
+    pass
+
+
+class NotFoundError(ReplicateScienceError):
+    pass
+
+
+class RateLimitError(ReplicateScienceError):
+    def __init__(self, message: str, resets_at: str | None = None):
+        super().__init__(message, status_code=429)
+        self.resets_at = resets_at
+
+
+class Client:
+    """ReplicateScience API client."""
+
+    def __init__(
+        self,
+        api_key: str | None = None,
+        base_url: str | None = None,
+        timeout: float = 30.0,
+    ):
+        self.api_key = api_key or os.environ.get("RS_API_KEY", "")
+        self.base_url = (base_url or DEFAULT_BASE_URL).rstrip("/")
+        self._http = httpx.Client(
+            base_url=self.base_url,
+            timeout=timeout,
+            headers=self._headers(),
+        )
+
+    def _headers(self) -> dict[str, str]:
+        h: dict[str, str] = {"User-Agent": "replicatescience-python/0.1.0"}
+        if self.api_key:
+            h["Authorization"] = f"Bearer {self.api_key}"
+        return h
+
+    def _request(self, method: str, path: str, **kwargs) -> dict:
+        resp = self._http.request(method, path, **kwargs)
+        if resp.status_code == 401:
+            raise AuthenticationError(
+                "Missing or invalid API key. Set RS_API_KEY or call rs.configure(api_key=...).",
+                status_code=401,
+            )
+        if resp.status_code == 404:
+            raise NotFoundError(
+                f"Resource not found: {path}",
+                status_code=404,
+            )
+        if resp.status_code == 429:
+            body = resp.json()
+            raise RateLimitError(
+                body.get("error", "Rate limit exceeded."),
+                resets_at=resp.headers.get("X-RateLimit-Reset"),
+            )
+        resp.raise_for_status()
+        return resp.json()
+
+    def _get(self, path: str, params: dict | None = None) -> dict:
+        return self._request("GET", path, params=params)
+
+    def search_protocols(
+        self,
+        query: str,
+        *,
+        species: str | None = None,
+        strain: str | None = None,
+        type: str | None = None,
+        year_min: int | None = None,
+        year_max: int | None = None,
+        sort: str | None = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> SearchResults:
+        params: dict = {"q": query, "page": page, "limit": limit}
+        if species:
+            params["species"] = species
+        if strain:
+            params["strain"] = strain
+        if type:
+            params["type"] = type
+        if year_min is not None:
+            params["year_min"] = year_min
+        if year_max is not None:
+            params["year_max"] = year_max
+        if sort:
+            params["sort"] = sort
+
+        data = self._get("/api/v1/protocols", params=params)
+        protocols = [Protocol.from_dict(p) for p in data.get("data", [])]
+        pagination = (
+            Pagination.from_dict(data["pagination"]) if "pagination" in data else None
+        )
+        rate_limit = (
+            RateLimit.from_dict(data["rate_limit"]) if "rate_limit" in data else None
+        )
+        return SearchResults(
+            protocols=protocols,
+            equipment=[],
+            results=[],
+            pagination=pagination,
+            rate_limit=rate_limit,
+        )
+
+    def get_protocol(self, slug: str) -> ProtocolDetail:
+        data = self._get(f"/api/v1/protocols/{slug}")
+        return ProtocolDetail.from_dict(data["data"])
+
+    def get_protocol_equipment(self, slug: str) -> list[Equipment]:
+        data = self._get(f"/api/v1/protocols/{slug}/equipment")
+        return [Equipment.from_dict(e) for e in data.get("data", [])]
+
+    def export_protocol(self, slug: str, format: str = "json") -> dict | str:
+        data = self._get(f"/api/v1/protocols/{slug}/export", params={"format": format})
+        return data
+
+    def search_equipment(
+        self,
+        query: str | None = None,
+        *,
+        category: str | None = None,
+        manufacturer: str | None = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> SearchResults:
+        params: dict = {"page": page, "limit": limit}
+        if query:
+            params["q"] = query
+        if category:
+            params["category"] = category
+        if manufacturer:
+            params["manufacturer"] = manufacturer
+
+        data = self._get("/api/v1/equipment", params=params)
+        equipment = [EquipmentDetail.from_dict(e) for e in data.get("data", [])]
+        pagination = (
+            Pagination.from_dict(data["pagination"]) if "pagination" in data else None
+        )
+        rate_limit = (
+            RateLimit.from_dict(data["rate_limit"]) if "rate_limit" in data else None
+        )
+        return SearchResults(
+            protocols=[],
+            equipment=equipment,
+            results=[],
+            pagination=pagination,
+            rate_limit=rate_limit,
+        )
+
+    def get_equipment(self, slug: str) -> EquipmentDetail:
+        data = self._get(f"/api/v1/equipment/{slug}")
+        return EquipmentDetail.from_dict(data["data"])
+
+    def unified_search(
+        self,
+        query: str,
+        *,
+        type: str | None = None,
+        page: int = 1,
+        limit: int = 20,
+    ) -> SearchResults:
+        params: dict = {"q": query, "page": page, "limit": limit}
+        if type:
+            params["type"] = type
+
+        data = self._get("/api/v1/search", params=params)
+        results = [SearchResult.from_dict(r) for r in data.get("data", [])]
+        pagination = (
+            Pagination.from_dict(data["pagination"]) if "pagination" in data else None
+        )
+        rate_limit = (
+            RateLimit.from_dict(data["rate_limit"]) if "rate_limit" in data else None
+        )
+        return SearchResults(
+            protocols=[],
+            equipment=[],
+            results=results,
+            pagination=pagination,
+            rate_limit=rate_limit,
+        )
+
+    def me(self) -> dict:
+        data = self._get("/api/v1/me")
+        return data["data"]
+
+    def close(self) -> None:
+        self._http.close()
+
+    def __enter__(self):
+        return self
+
+    def __exit__(self, *args):
+        self.close()

replicatescience-0.1.0/src/replicatescience/export.py

@@ -0,0 +1,42 @@
+"""Export and import protocols as YAML/JSON files."""
+
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+import yaml
+
+from replicatescience.models import ProtocolDetail
+
+
+def save_protocol(protocol: ProtocolDetail, path: str) -> None:
+    """Save a protocol to a YAML or JSON file."""
+    p = Path(path)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    data = protocol.to_dict()
+
+    if p.suffix in (".yaml", ".yml"):
+        with open(p, "w", encoding="utf-8") as f:
+            yaml.dump(data, f, default_flow_style=False, sort_keys=False, allow_unicode=True)
+    elif p.suffix == ".json":
+        with open(p, "w", encoding="utf-8") as f:
+            json.dump(data, f, indent=2, ensure_ascii=False)
+    else:
+        raise ValueError(f"Unsupported format: {p.suffix}. Use .yaml, .yml, or .json")
+
+
+def load_protocol(path: str) -> ProtocolDetail:
+    """Load a protocol from a YAML or JSON file."""
+    p = Path(path)
+
+    if p.suffix in (".yaml", ".yml"):
+        with open(p, "r", encoding="utf-8") as f:
+            data = yaml.safe_load(f)
+    elif p.suffix == ".json":
+        with open(p, "r", encoding="utf-8") as f:
+            data = json.load(f)
+    else:
+        raise ValueError(f"Unsupported format: {p.suffix}. Use .yaml, .yml, or .json")
+
+    return ProtocolDetail.from_dict(data)

replicatescience-0.1.0/src/replicatescience/models.py

@@ -0,0 +1,483 @@
+"""Data models for ReplicateScience API responses."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import Any
+
+
+@dataclass
+class Pagination:
+    page: int
+    limit: int
+    total: int
+    next: str | None = None
+    previous: str | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Pagination:
+        return cls(
+            page=d["page"],
+            limit=d["limit"],
+            total=d["total"],
+            next=d.get("next"),
+            previous=d.get("previous"),
+        )
+
+
+@dataclass
+class RateLimit:
+    limit: int
+    remaining: int
+    resets_at: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> RateLimit:
+        return cls(
+            limit=d["limit"],
+            remaining=d["remaining"],
+            resets_at=d["resets_at"],
+        )
+
+
+@dataclass
+class Paper:
+    title: str
+    doi: str | None = None
+    authors: list[str] = field(default_factory=list)
+    journal: str | None = None
+    year: int | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Paper:
+        return cls(
+            title=d["title"],
+            doi=d.get("doi"),
+            authors=d.get("authors", []),
+            journal=d.get("journal"),
+            year=d.get("year"),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "title": self.title,
+            "doi": self.doi,
+            "authors": self.authors,
+            "journal": self.journal,
+            "year": self.year,
+        }
+
+
+@dataclass
+class ProcedureStep:
+    number: int
+    title: str | None
+    description: str
+    duration: str | None = None
+    evidence: str | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> ProcedureStep:
+        return cls(
+            number=d["number"],
+            title=d.get("title"),
+            description=d["description"],
+            duration=d.get("duration"),
+            evidence=d.get("evidence"),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "number": self.number,
+            "title": self.title,
+            "description": self.description,
+            "duration": self.duration,
+            "evidence": self.evidence,
+        }
+
+
+@dataclass
+class EvidenceQuote:
+    quote: str
+    context: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> EvidenceQuote:
+        return cls(quote=d["quote"], context=d["context"])
+
+    def to_dict(self) -> dict:
+        return {"quote": self.quote, "context": self.context}
+
+
+@dataclass
+class Equipment:
+    id: str
+    name: str
+    slug: str
+    category: str | None = None
+    manufacturer: str | None = None
+    model_number: str | None = None
+    rrid: str | None = None
+    product_url: str | None = None
+    price_estimate: float | None = None
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Equipment:
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            slug=d["slug"],
+            category=d.get("category"),
+            manufacturer=d.get("manufacturer"),
+            model_number=d.get("model_number"),
+            rrid=d.get("rrid"),
+            product_url=d.get("product_url"),
+            price_estimate=d.get("price_estimate"),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "slug": self.slug,
+            "category": self.category,
+            "manufacturer": self.manufacturer,
+            "model_number": self.model_number,
+            "rrid": self.rrid,
+            "product_url": self.product_url,
+            "price_estimate": self.price_estimate,
+        }
+
+
+@dataclass
+class Product:
+    name: str
+    url: str
+    price: float | None
+    sku: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Product:
+        return cls(
+            name=d["name"],
+            url=d["url"],
+            price=d.get("price"),
+            sku=d["sku"],
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "name": self.name,
+            "url": self.url,
+            "price": self.price,
+            "sku": self.sku,
+        }
+
+
+@dataclass
+class EquipmentDetail(Equipment):
+    aliases: list[str] = field(default_factory=list)
+    description: str | None = None
+    product: Product | None = None
+    protocol_count: int = 0
+    url: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict) -> EquipmentDetail:
+        product = None
+        if d.get("product"):
+            product = Product.from_dict(d["product"])
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            slug=d["slug"],
+            category=d.get("category"),
+            manufacturer=d.get("manufacturer"),
+            model_number=d.get("model_number"),
+            rrid=d.get("rrid"),
+            product_url=d.get("product_url"),
+            price_estimate=d.get("price_estimate"),
+            aliases=d.get("aliases", []),
+            description=d.get("description"),
+            product=product,
+            protocol_count=d.get("protocol_count", 0),
+            url=d.get("url", ""),
+        )
+
+
+@dataclass
+class Protocol:
+    id: str
+    name: str
+    slug: str
+    paper: Paper
+    type: str | None = None
+    species: str | None = None
+    strain: str | None = None
+    equipment_count: int = 0
+    step_count: int = 0
+    evidence_score: float | None = None
+    tags: list[str] = field(default_factory=list)
+    url: str = ""
+    created_at: str = ""
+
+    @classmethod
+    def from_dict(cls, d: dict) -> Protocol:
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            slug=d["slug"],
+            paper=Paper.from_dict(d["paper"]),
+            type=d.get("type"),
+            species=d.get("species"),
+            strain=d.get("strain"),
+            equipment_count=d.get("equipment_count", 0),
+            step_count=d.get("step_count", 0),
+            evidence_score=d.get("evidence_score"),
+            tags=d.get("tags", []),
+            url=d.get("url", ""),
+            created_at=d.get("created_at", ""),
+        )
+
+    def to_dict(self) -> dict:
+        return {
+            "id": self.id,
+            "name": self.name,
+            "slug": self.slug,
+            "paper": self.paper.to_dict(),
+            "type": self.type,
+            "species": self.species,
+            "strain": self.strain,
+            "equipment_count": self.equipment_count,
+            "step_count": self.step_count,
+            "evidence_score": self.evidence_score,
+            "tags": self.tags,
+            "url": self.url,
+            "created_at": self.created_at,
+        }
+
+
+@dataclass
+class ProtocolDetail(Protocol):
+    brain_regions: list[str] = field(default_factory=list)
+    steps: list[ProcedureStep] = field(default_factory=list)
+    equipment: list[Equipment] = field(default_factory=list)
+    subjects: dict[str, Any] | None = None
+    analysis: dict[str, Any] | None = None
+    evidence_quotes: list[EvidenceQuote] = field(default_factory=list)
+
+    @classmethod
+    def from_dict(cls, d: dict) -> ProtocolDetail:
+        return cls(
+            id=d["id"],
+            name=d["name"],
+            slug=d["slug"],
+            paper=Paper.from_dict(d["paper"]),
+            type=d.get("type"),
+            species=d.get("species"),
+            strain=d.get("strain"),
+            equipment_count=d.get("equipment_count", 0),
+            step_count=d.get("step_count", 0),
+            evidence_score=d.get("evidence_score"),
+            tags=d.get("tags", []),
+            url=d.get("url", ""),
+            created_at=d.get("created_at", ""),
+            brain_regions=d.get("brain_regions", []),
+            steps=[ProcedureStep.from_dict(s) for s in d.get("steps", [])],
+            equipment=[Equipment.from_dict(e) for e in d.get("equipment", [])],
+            subjects=d.get("subjects"),
+            analysis=d.get("analysis"),
+            evidence_quotes=[
+                EvidenceQuote.from_dict(q) for q in d.get("evidence_quotes", [])
+            ],
+        )
+
+    def to_dict(self) -> dict:
+        base = super().to_dict()
+        base.update(
+            {
+                "brain_regions": self.brain_regions,
+                "steps": [s.to_dict() for s in self.steps],
+                "equipment": [e.to_dict() for e in self.equipment],
+                "subjects": self.subjects,
+                "analysis": self.analysis,
+                "evidence_quotes": [q.to_dict() for q in self.evidence_quotes],
+            }
+        )
+        return base
+
+
+@dataclass
+class SearchResult:
+    type: str
+    id: str
+    name: str
+    slug: str
+    description: str
+    url: str
+
+    @classmethod
+    def from_dict(cls, d: dict) -> SearchResult:
+        return cls(
+            type=d["type"],
+            id=d["id"],
+            name=d["name"],
+            slug=d["slug"],
+            description=d.get("description", ""),
+            url=d.get("url", ""),
+        )
+
+
+@dataclass
+class SearchResults:
+    protocols: list[Protocol]
+    equipment: list[Equipment]
+    results: list[SearchResult]
+    pagination: Pagination | None = None
+    rate_limit: RateLimit | None = None
+
+
+@dataclass
+class DiffChange:
+    field: str
+    label: str
+    old: Any
+    new: Any
+
+
+@dataclass
+class ProtocolDiff:
+    protocol_a: str
+    protocol_b: str
+    changes: list[DiffChange] = field(default_factory=list)
+
+    @property
+    def summary(self) -> str:
+        n = len(self.changes)
+        sections = len({c.field.split(".")[0] for c in self.changes})
+        if n == 0:
+            return "No differences found."
+        return f"{n} change{'s' if n != 1 else ''} across {sections} section{'s' if sections != 1 else ''}"
+
+    def to_markdown(self) -> str:
+        lines = [
+            f"# Protocol Diff",
+            f"**A:** {self.protocol_a}",
+            f"**B:** {self.protocol_b}",
+            f"**Summary:** {self.summary}",
+            "",
+        ]
+        for c in self.changes:
+            lines.append(f"## {c.label}")
+            lines.append(f"- **A:** {c.old}")
+            lines.append(f"- **B:** {c.new}")
+            lines.append("")
+        return "\n".join(lines)
+
+    @classmethod
+    def compute(cls, a: ProtocolDetail, b: ProtocolDetail) -> ProtocolDiff:
+        changes: list[DiffChange] = []
+
+        # Compare metadata fields
+        for field_name, label in [
+            ("name", "Name"),
+            ("type", "Type"),
+            ("species", "Species"),
+            ("strain", "Strain"),
+        ]:
+            va = getattr(a, field_name)
+            vb = getattr(b, field_name)
+            if va != vb:
+                changes.append(DiffChange(field=field_name, label=label, old=va, new=vb))
+
+        # Compare tags
+        if set(a.tags) != set(b.tags):
+            changes.append(
+                DiffChange(field="tags", label="Tags", old=a.tags, new=b.tags)
+            )
+
+        # Compare brain regions
+        if set(a.brain_regions) != set(b.brain_regions):
+            changes.append(
+                DiffChange(
+                    field="brain_regions",
+                    label="Brain Regions",
+                    old=a.brain_regions,
+                    new=b.brain_regions,
+                )
+            )
+
+        # Compare step count
+        if a.step_count != b.step_count:
+            changes.append(
+                DiffChange(
+                    field="steps.count",
+                    label="Step Count",
+                    old=a.step_count,
+                    new=b.step_count,
+                )
+            )
+
+        # Compare individual steps
+        max_steps = max(len(a.steps), len(b.steps))
+        for i in range(max_steps):
+            sa = a.steps[i] if i < len(a.steps) else None
+            sb = b.steps[i] if i < len(b.steps) else None
+            if sa is None:
+                changes.append(
+                    DiffChange(
+                        field=f"steps.{i + 1}",
+                        label=f"Step {i + 1}",
+                        old="(missing)",
+                        new=sb.description if sb else "",
+                    )
+                )
+            elif sb is None:
+                changes.append(
+                    DiffChange(
+                        field=f"steps.{i + 1}",
+                        label=f"Step {i + 1}",
+                        old=sa.description,
+                        new="(missing)",
+                    )
+                )
+            elif sa.description != sb.description:
+                changes.append(
+                    DiffChange(
+                        field=f"steps.{i + 1}",
+                        label=f"Step {i + 1}: {sa.title or sb.title or ''}".strip(": "),
+                        old=sa.description,
+                        new=sb.description,
+                    )
+                )
+
+        # Compare equipment
+        equip_a = {e.slug for e in a.equipment}
+        equip_b = {e.slug for e in b.equipment}
+        if equip_a != equip_b:
+            only_a = equip_a - equip_b
+            only_b = equip_b - equip_a
+            if only_a:
+                changes.append(
+                    DiffChange(
+                        field="equipment.removed",
+                        label="Equipment (only in A)",
+                        old=sorted(only_a),
+                        new="(not present)",
+                    )
+                )
+            if only_b:
+                changes.append(
+                    DiffChange(
+                        field="equipment.added",
+                        label="Equipment (only in B)",
+                        old="(not present)",
+                        new=sorted(only_b),
+                    )
+                )
+
+        return cls(
+            protocol_a=a.slug,
+            protocol_b=b.slug,
+            changes=changes,
+        )