entitysdk 0.2.1__tar.gz → 0.2.3__tar.gz

{entitysdk-0.2.1/src/entitysdk.egg-info → entitysdk-0.2.3}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: entitysdk
-Version: 0.2.1
+Version: 0.2.3
 Summary: Python library for interacting with the entitycore service
 Author-email: Open Brain Institute <info@openbraininstitute.org>
 Maintainer-email: Open Brain Institute <info@openbraininstitute.org>
@@ -39,6 +39,21 @@ entitysdk is a Python library for interacting with the [entitycore service][enti
 ```bash
 pip install entitysdk
 ```
+
+## Obtaining a valid access token
+
+An access token can be retrieved easily using the obi-auth helper library.
+
+```bash
+pip install obi-auth
+```
+
+```python
+from obi_auth import get_token
+
+access_token = get_token(environment="staging")
+```
+
 ## Quick Start
 
 ```python
@@ -49,11 +64,11 @@ from entitysdk.models.morphology import ReconstructionMorphology
 
 # Initialize client
 client = Client(
-    api_url="http://api.example.com",
     project_context=ProjectContext(
         project_id=UUID("your-project-id"),
         virtual_lab_id=UUID("your-lab-id")
     )
+    environment="staging"
 )
 
 # Search for morphologies

{entitysdk-0.2.1 → entitysdk-0.2.3}/README.md

@@ -18,6 +18,21 @@ entitysdk is a Python library for interacting with the [entitycore service][enti
 ```bash
 pip install entitysdk
 ```
+
+## Obtaining a valid access token
+
+An access token can be retrieved easily using the obi-auth helper library.
+
+```bash
+pip install obi-auth
+```
+
+```python
+from obi_auth import get_token
+
+access_token = get_token(environment="staging")
+```
+
 ## Quick Start
 
 ```python
@@ -28,11 +43,11 @@ from entitysdk.models.morphology import ReconstructionMorphology
 
 # Initialize client
 client = Client(
-    api_url="http://api.example.com",
     project_context=ProjectContext(
         project_id=UUID("your-project-id"),
         virtual_lab_id=UUID("your-lab-id")
     )
+    environment="staging"
 )
 
 # Search for morphologies

entitysdk-0.2.1/examples/searching.ipynb → entitysdk-0.2.3/examples/01_searching.ipynb

@@ -13,14 +13,15 @@
     "\n",
     "from entitysdk.client import Client\n",
     "from entitysdk.common import ProjectContext\n",
-    "from entitysdk.models.agent import Organization, Person\n",
-    "from entitysdk.models.contribution import Role\n",
-    "from entitysdk.models.morphology import (\n",
+    "from entitysdk.models import (\n",
+    "    MTypeClass,\n",
+    "    Organization,\n",
+    "    Person,\n",
     "    ReconstructionMorphology,\n",
+    "    Role,\n",
     "    Species,\n",
     "    Strain,\n",
     ")\n",
-    "from entitysdk.models.mtype import MTypeClass\n",
     "\n",
     "entitycore_api_url = \"http://127.0.0.1:8000\"\n",
     "project_context = ProjectContext(\n",
@@ -28,7 +29,13 @@
     "    project_id=\"0dbced5f-cc3d-488a-8c7f-cfb8ea039dc6\",\n",
     ")\n",
     "client = Client(api_url=entitycore_api_url, project_context=project_context)\n",
-    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")"
+    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")\n",
+    "\n",
+    "# uncomment for staging\n",
+    "# from obi_auth import get_token\n",
+    "\n",
+    "# token = get_token(environment=\"staging\")\n",
+    "# client = Client(environment=\"staging\")"
    ]
   },
   {
@@ -239,7 +246,7 @@
    "id": "fae8506b-9cbc-433b-a17d-6ce3d84bcf4c",
    "metadata": {},
    "source": [
-    "## Find morphologies of a specifix mtype id"
+    "## Find morphologies by mtype"
    ]
   },
   {
@@ -282,7 +289,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.9"
+   "version": "3.12.10"
   }
  },
  "nbformat": 4,

entitysdk-0.2.1/examples/morphology.ipynb → entitysdk-0.2.3/examples/02_morphology.ipynb

@@ -16,7 +16,7 @@
     "\n",
     "from entitysdk.client import Client\n",
     "from entitysdk.common import ProjectContext\n",
-    "from entitysdk.models.morphology import (\n",
+    "from entitysdk.models import (\n",
     "    BrainLocation,\n",
     "    BrainRegion,\n",
     "    ReconstructionMorphology,\n",
@@ -46,7 +46,14 @@
     "    project_id=\"0dbced5f-cc3d-488a-8c7f-cfb8ea039dc6\",\n",
     ")\n",
     "client = Client(api_url=entitycore_api_url, project_context=project_context)\n",
-    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")"
+    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")\n",
+    "\n",
+    "# uncomment for staging\n",
+    "# from obi_auth import get_token\n",
+    "# token = get_token(environment=\"staging\")\n",
+    "# Replace this with your vlab project url in staging\n",
+    "# project_context = ProjectContext.from_vlab_url(\"https://staging.openbraininstitute.org/app/virtual-lab/lab/594fd60d-7a38-436f-939d-500feaa13bba/project/ff89ca07-6613-4922-9ab0-2637221db8b5/home\")\n",
+    "# client = Client(environment=\"staging\", project_context=project_context)"
    ]
   },
   {
@@ -92,13 +99,35 @@
   {
    "cell_type": "code",
    "execution_count": null,
-   "id": "45d75d53-71f1-4213-8355-4937c1e27558",
+   "id": "e5dde536-0c58-4d42-a834-1b1a0ec17e9d",
    "metadata": {},
    "outputs": [],
    "source": [
     "rprint(strain)"
    ]
   },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "5d42a174-9737-4477-830a-3dc908dea925",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "brain_region = client.search_entity(\n",
+    "    entity_type=BrainRegion, query={\"annotation_value\": 68}, token=token\n",
+    ").one()"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "282200cd-ad0c-4bb3-bc21-88de85289179",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "rprint(brain_region)"
+   ]
+  },
   {
    "cell_type": "markdown",
    "id": "a0193055-3448-4d1c-99cc-4d953727ef4e",
@@ -114,19 +143,11 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "# No GET endpoint yet for brain-region\n",
-    "\n",
     "brain_location = BrainLocation(\n",
     "    x=4101.52490234375,\n",
     "    y=1173.8499755859375,\n",
     "    z=4744.60009765625,\n",
     ")\n",
-    "brain_region = BrainRegion(\n",
-    "    id=68,\n",
-    "    name=\"Frontal pole, layer 1\",\n",
-    "    acronym=\"FRP1\",\n",
-    "    children=[],\n",
-    ")\n",
     "morphology = ReconstructionMorphology(\n",
     "    name=\"my-morph\",\n",
     "    description=\"A morphology\",\n",
@@ -153,7 +174,25 @@
    "id": "83fb7e5e-73b5-4227-aa22-90bb789b0907",
    "metadata": {},
    "source": [
-    "## Register morphology and upload assets"
+    "## Register morphology"
+   ]
+  },
+  {
+   "cell_type": "code",
+   "execution_count": null,
+   "id": "2e32a168",
+   "metadata": {},
+   "outputs": [],
+   "source": [
+    "registered = client.register_entity(entity=morphology, token=token)"
+   ]
+  },
+  {
+   "cell_type": "markdown",
+   "id": "c0d500bd",
+   "metadata": {},
+   "source": [
+    "## Upload assets"
    ]
   },
   {
@@ -163,8 +202,6 @@
    "metadata": {},
    "outputs": [],
    "source": [
-    "registered = client.register_entity(entity=morphology, token=token)\n",
-    "\n",
     "with tempfile.TemporaryDirectory() as tdir:\n",
     "    file1 = Path(tdir, \"morph.h5\")\n",
     "    file1.write_text(\"h5\")\n",
@@ -428,7 +465,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.9"
+   "version": "3.12.10"
   }
  },
  "nbformat": 4,

entitysdk-0.2.1/examples/contribution.ipynb → entitysdk-0.2.3/examples/03_contribution.ipynb

@@ -13,9 +13,7 @@
     "\n",
     "from entitysdk.client import Client\n",
     "from entitysdk.common import ProjectContext\n",
-    "from entitysdk.models.agent import Organization\n",
-    "from entitysdk.models.contribution import Contribution, Role\n",
-    "from entitysdk.models.morphology import ReconstructionMorphology\n",
+    "from entitysdk.models import Contribution, Organization, ReconstructionMorphology, Role\n",
     "\n",
     "entitycore_api_url = \"http://127.0.0.1:8000\"\n",
     "project_context = ProjectContext(\n",
@@ -23,7 +21,14 @@
     "    project_id=\"0dbced5f-cc3d-488a-8c7f-cfb8ea039dc6\",\n",
     ")\n",
     "client = Client(api_url=entitycore_api_url, project_context=project_context)\n",
-    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")"
+    "token = os.getenv(\"ACCESS_TOKEN\", \"XXX\")\n",
+    "\n",
+    "# uncomment for staging\n",
+    "# from obi_auth import get_token\n",
+    "# token = get_token(environment=\"staging\")\n",
+    "# Replace this with your vlab project url in staging\n",
+    "# project_context = ProjectContext.from_vlab_url(\"https://staging.openbraininstitute.org/app/virtual-lab/lab/594fd60d-7a38-436f-939d-500feaa13bba/project/ff89ca07-6613-4922-9ab0-2637221db8b5/home\")\n",
+    "# client = Client(environment=\"staging\", project_context=project_context)"
    ]
   },
   {
@@ -82,7 +87,7 @@
    "outputs": [],
    "source": [
     "morphology = client.search_entity(\n",
-    "    entity_type=ReconstructionMorphology, token=token, limit=1\n",
+    "    entity_type=ReconstructionMorphology, token=token, limit=1, query={\"name__ilike\": \"my-morph\"}\n",
     ").first()"
    ]
   },
@@ -135,6 +140,8 @@
    "metadata": {},
    "outputs": [],
    "source": [
+    "# Note: It will fail if registered twice\n",
+    "# because there is a uniqueness constraint on (agent, morphology_id)\n",
     "registered = client.register_entity(entity=contribution, token=token)"
    ]
   },
@@ -193,7 +200,7 @@
    "name": "python",
    "nbconvert_exporter": "python",
    "pygments_lexer": "ipython3",
-   "version": "3.12.9"
+   "version": "3.12.10"
   }
  },
  "nbformat": 4,

{entitysdk-0.2.1 → entitysdk-0.2.3}/src/entitysdk/client.py

@@ -13,7 +13,7 @@ from entitysdk.models.asset import Asset, LocalAssetMetadata
 from entitysdk.models.core import Identifiable
 from entitysdk.result import IteratorResult
 from entitysdk.token_manager import TokenManager
-from entitysdk.typedef import ID, DeploymentEnvironment
+from entitysdk.types import ID, DeploymentEnvironment
 from entitysdk.util import build_api_url
 
 

{entitysdk-0.2.1 → entitysdk-0.2.3}/src/entitysdk/common.py

@@ -7,7 +7,7 @@ from uuid import UUID
 from pydantic import BaseModel
 
 from entitysdk.exception import EntitySDKError
-from entitysdk.typedef import DeploymentEnvironment
+from entitysdk.types import DeploymentEnvironment
 
 UUID_RE = "[0-9a-f]{8}(?:-[0-9a-f]{4}){3}-[0-9a-f]{12}"
 

entitysdk-0.2.3/src/entitysdk/models/__init__.py

@@ -0,0 +1,37 @@
+"""Models for entitysdk."""
+
+from entitysdk.models.agent import Organization, Person
+from entitysdk.models.asset import Asset
+from entitysdk.models.brain_location import BrainLocation
+from entitysdk.models.brain_region import BrainRegion
+from entitysdk.models.contribution import Contribution, Role
+from entitysdk.models.electrical_cell_recording import ElectricalCellRecording
+from entitysdk.models.emodel import EModel
+from entitysdk.models.ion_channel_model import IonChannelModel, NeuronBlock, UseIon
+from entitysdk.models.license import License
+from entitysdk.models.memodel import MEModel
+from entitysdk.models.morphology import ReconstructionMorphology
+from entitysdk.models.mtype import MTypeClass
+from entitysdk.models.taxonomy import Species, Strain, Taxonomy
+
+__all__ = [
+    "Asset",
+    "BrainLocation",
+    "BrainRegion",
+    "Contribution",
+    "ElectricalCellRecording",
+    "EModel",
+    "IonChannelModel",
+    "License",
+    "MEModel",
+    "MTypeClass",
+    "NeuronBlock",
+    "Organization",
+    "Person",
+    "ReconstructionMorphology",
+    "Role",
+    "Species",
+    "Strain",
+    "Taxonomy",
+    "UseIon",
+]

entitysdk-0.2.3/src/entitysdk/models/brain_location.py

@@ -0,0 +1,33 @@
+"""Brain location model."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from entitysdk.models.core import Struct
+
+
+class BrainLocation(Struct):
+    """BrainLocation model."""
+
+    x: Annotated[
+        float,
+        Field(
+            examples=[1.0, 2.0, 3.0],
+            description="The x coordinate of the brain location.",
+        ),
+    ]
+    y: Annotated[
+        float,
+        Field(
+            examples=[1.0, 2.0, 3.0],
+            description="The y coordinate of the brain location.",
+        ),
+    ]
+    z: Annotated[
+        float,
+        Field(
+            examples=[1.0, 2.0, 3.0],
+            description="The z coordinate of the brain location.",
+        ),
+    ]

entitysdk-0.2.3/src/entitysdk/models/brain_region.py

@@ -0,0 +1,37 @@
+"""BrainRegion model."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from entitysdk.models.core import Identifiable
+from entitysdk.types import ID
+
+
+class BrainRegion(Identifiable):
+    """BrainRegion model."""
+
+    name: Annotated[
+        str,
+        Field(
+            examples=["Thalamus"],
+            description="The name of the brain region.",
+        ),
+    ]
+    annotation_value: Annotated[
+        int, Field(examples=[997], description="The annotation voxel value.")
+    ]
+    acronym: Annotated[
+        str,
+        Field(
+            examples=["TH"],
+            description="The acronym of the brain region.",
+        ),
+    ]
+    parent_structure_id: Annotated[
+        ID | None, Field(examples=[], description="The parent region structure UUID.")
+    ]
+    hierarchy_id: Annotated[
+        ID, Field(examples=[], description="The brain hierarchy that includes this brain region.")
+    ]
+    color_hex_triplet: Annotated[str, Field(description="Region's color hex triplet.")]

{entitysdk-0.2.1 → entitysdk-0.2.3}/src/entitysdk/models/contribution.py

@@ -6,7 +6,6 @@ from pydantic import Field
 
 from entitysdk.models.agent import AgentUnion
 from entitysdk.models.core import Identifiable
-from entitysdk.models.entity import Entity
 
 
 class Role(Identifiable):
@@ -42,6 +41,12 @@ class Contribution(Identifiable):
         ),
     ]
     entity: Annotated[
-        Entity | None,
+        "Entity | None",
         Field(description="The entity that resulted in this contribution."),
     ] = None
+
+
+# Update forward reference for Entity
+from entitysdk.models.entity import Entity  # noqa: E402
+
+Contribution.model_rebuild(force=True)

{entitysdk-0.2.1 → entitysdk-0.2.3}/src/entitysdk/models/core.py

@@ -6,7 +6,7 @@ from typing import Annotated
 from pydantic import Field
 
 from entitysdk.models.base import BaseModel
-from entitysdk.typedef import ID
+from entitysdk.types import ID
 
 
 class Struct(BaseModel):

entitysdk-0.2.3/src/entitysdk/models/electrical_cell_recording.py

@@ -0,0 +1,92 @@
+"""Electrical cell recording models."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from entitysdk.models.brain_region import BrainRegion
+from entitysdk.models.entity import Entity
+from entitysdk.models.license import License
+from entitysdk.models.subject import Subject
+from entitysdk.types import (
+    ElectricalRecordingOrigin,
+    ElectricalRecordingStimulusShape,
+    ElectricalRecordingStimulusType,
+    ElectricalRecordingType,
+)
+
+
+class ElectricalRecordingStimulus(Entity):
+    """Electrical cell recording stimulus model."""
+
+    dt: float | None = None
+    injection_type: ElectricalRecordingStimulusType
+    shape: ElectricalRecordingStimulusShape
+    start_time: float | None = None
+    end_time: float | None = None
+
+
+class ElectricalCellRecording(Entity):
+    """Electrical cell recording model."""
+
+    ljp: Annotated[
+        float,
+        Field(
+            title="Liquid Junction Potential",
+            description="Correction applied to the voltage trace, in mV",
+            examples=[0.1],
+        ),
+    ] = 0.0
+    recording_location: Annotated[
+        list[str],
+        Field(
+            title="Recording Location",
+            description=(
+                "Location on the cell where recording was performed, in hoc-compatible format."
+            ),
+        ),
+    ]
+    recording_type: Annotated[
+        ElectricalRecordingType,
+        Field(
+            title="Recording Type",
+            description="Recording type.",
+        ),
+    ]
+    recording_origin: Annotated[
+        ElectricalRecordingOrigin,
+        Field(
+            title="Recording Origin",
+            description="Recording origin.",
+        ),
+    ]
+    comment: Annotated[
+        str | None,
+        Field(
+            title="Comment",
+            description="Comment with further details.",
+        ),
+    ] = None
+    brain_region: Annotated[
+        BrainRegion,
+        Field(
+            description="The region of the brain where the morphology is located.",
+        ),
+    ]
+    subject: Annotated[
+        Subject,
+        Field(title="Subject", description="The subject of the electrical cell recording."),
+    ]
+    stimuli: Annotated[
+        list[ElectricalRecordingStimulus] | None,
+        Field(
+            title="Electrical Recording Stimuli",
+            description="List of stimuli applied to the cell with their respective time steps",
+        ),
+    ] = None
+    license: Annotated[
+        License | None,
+        Field(
+            description="The license attached to the morphology.",
+        ),
+    ] = None

entitysdk-0.2.3/src/entitysdk/models/emodel.py

@@ -0,0 +1,89 @@
+"""Electrical cell model."""
+
+from typing import Annotated
+
+from pydantic import Field
+
+from entitysdk.models.contribution import Contribution
+from entitysdk.models.entity import Entity
+from entitysdk.models.etype import ETypeClass
+from entitysdk.models.ion_channel_model import IonChannelModel
+from entitysdk.models.morphology import (
+    BrainRegion,
+    License,
+    ReconstructionMorphology,
+    Species,
+    Strain,
+)
+from entitysdk.models.mtype import MTypeClass
+
+
+class EModel(Entity):
+    """Electrical cell model."""
+
+    species: Annotated[
+        Species,
+        Field(description="The species for which the emodel applies."),
+    ]
+    strain: Annotated[
+        Strain | None,
+        Field(description="The specific strain of the species, if applicable."),
+    ] = None
+    brain_region: Annotated[
+        BrainRegion,
+        Field(description="The brain region where the emodel is used or applies."),
+    ]
+    license: Annotated[
+        License | None,
+        Field(description="License under which the emodel is distributed."),
+    ] = None
+    contributions: Annotated[
+        list[Contribution] | None,
+        Field(description="List of contributions related to this emodel."),
+    ] = None
+    iteration: Annotated[
+        str,
+        Field(
+            description="The iteration of the emodel used during optimisation.",
+            examples="1372346",
+        ),
+    ]
+    score: Annotated[
+        float,
+        Field(
+            description="The score of the emodel gotten during validation.",
+            examples=54.0,
+        ),
+    ]
+    seed: Annotated[
+        int,
+        Field(
+            description="The RNG seed used during optimisation.",
+            examples=13,
+        ),
+    ]
+    exemplar_morphology: Annotated[
+        ReconstructionMorphology | None,
+        Field(
+            description="The morphology used during optimisation.",
+        ),
+    ] = None
+    etypes: Annotated[
+        list[ETypeClass] | None,
+        Field(
+            description="The etype classes of the emodel.",
+        ),
+    ] = None
+    mtypes: Annotated[
+        list[MTypeClass] | None,
+        Field(
+            description="The mtype classes of the emodel.",
+        ),
+    ] = None
+    ion_channel_models: Annotated[
+        list[IonChannelModel] | None,
+        Field(
+            description="List of ion channel models.",
+        ),
+    ] = None
+    legacy_id: list[str] | None = None