update documentation

docs/case-studies/dynotx-recommended-sop.md

@@ -3,7 +3,7 @@ Below, you will find the SOP Dyno Therapeutics follows for using Liminal to mana
 ## Dyno Therapeutics Benchling Change Management SOP
 (since 07.24.2024)
 
-Dyno's Benchling tenants are set up as a Dev, Test, and Prod environments. All scientists and a select number of engineers have access to the PROD tenant, and all work is done in PROD. The Dev and Test tenants are used for development and testing of new features before merging into PROD. Limianl is used to keep the Test and Prod tenants in sync, while Dev is used for development/testing. Dyno uses a Slack channel for requesting changes to Benchling schemas. There is one Benchling Admin who is responsible for managing the Benchling environment.
+Dyno's Benchling tenants are set up as a Dev, Test, and Prod environments. All scientists and a select number of engineers have access to the PROD tenant, and all work is done in PROD. The Dev and Test tenants are used for development and testing of new features before merging into PROD. Liminal is used to keep the Test and Prod tenants in sync, while Dev is used for development/testing. Dyno uses a Slack channel for requesting changes to Benchling schemas. There is one Benchling Admin who is responsible for managing the Benchling environment.
 
 Let's say a change has to be made to the Benchling schema...
 

docs/reference/benchling-connection.md

@@ -1,4 +1,4 @@
-## BenchlingConnection ([class](https://github.com/dynotx/liminal-orm/blob/main/liminal/connection/benchling_connection.py))
+## BenchlingConnection: [class](https://github.com/dynotx/liminal-orm/blob/main/liminal/connection/benchling_connection.py)
 
 The `BenchlingConnection` class is used to define the connection information for a particular Benchling tenant. The BenchlingConnection class is defined in your `env.py` file and it also used to create a BenchlingService object. In the `env.py` file, the api_client and internal_api parameters are required for the BenchlingConnection object in orderto be used in the migration service. The BenchlingService can be imported from the liminal pacakage and be used to connect to [Benchling's SDK](https://docs.benchling.com/docs/getting-started-with-the-sdk), internal API, and/or Postgres warehouse.
 

docs/reference/benchling-session.md

@@ -0,0 +1,40 @@
+## BenchlingService: [class](https://github.com/dynotx/liminal-orm/blob/main/liminal/connection/benchling_service.py)
+
+The BenchlingService class takes in a BenchlingConnection object and is used to directly interact with Benchling's SDK, internal API, and Postgres warehouse. This class is surfaced for users so that there is one standard interface for interacting with Benchling around your codebase. Liminal's BenchlingService handles all session management and is a subclass of Benchling's SDK, so all functionality of Benchling's SDK is available.
+
+BenchlingService can be used to build on top of Liminal's ORM. Below is an example of how to use the BenchlingService class.
+
+```python
+from liminal.connection import BenchlingConnection
+from liminal.connection import BenchlingService
+
+connection = BenchlingConnection(
+    ...
+)
+benchling_service = BenchlingService(connection, use_internal_api=True, use_warehouse=True) # enable all connections
+
+# Use Benchling SDK
+entity = benchling_service.custom_entities.get_by_id("my-entity-id")
+
+# Use to query Postgres warehouse using SQLAlchemy
+with benchling_service() as session:
+    entity = session.query(Pizza).all()
+```
+
+### Parameters
+
+**connection: BenchlingConnection**
+
+> The connection object that contains the credentials for the Benchling tenant.
+
+**use_api: bool**
+
+> Whether to connect to the Benchling SDK. Defaults to True. (See Benchling SDK documentation [here](https://docs.benchling.com/docs/getting-started-with-the-sdk))
+
+**use_internal_api: bool**
+
+> Whether to connect to the Benchling internal API. Defaults to False.
+
+**use_warehouse: bool**
+
+> Whether to connect to the Benchling Postgres warehouse. Defaults to False. See SQLAlchemy documentation [here](https://www.sqlalchemy.org/) for more information.

docs/reference/dropdowns.md

@@ -1,4 +1,4 @@
-## Dropdown Schema ([class](https://github.com/dynotx/liminal-orm/blob/main/liminal/base/base_dropdown.py))
+## Dropdown Schema: [class](https://github.com/dynotx/liminal-orm/blob/main/liminal/base/base_dropdown.py)
 
 Below is an example of a dropdown schema defined in code. The `__benchling_name__` property is used to define the name of the dropdown in Benchling, while the `__allowed_values__` property is used to define the values of the dropdown.
 

docs/reference/entity-schemas.md

@@ -1,5 +1,5 @@
 
-## Entity Schema ([class](https://github.com/dynotx/liminal-orm/blob/main/liminal/orm/base_model.py))
+## Entity Schema: [class](https://github.com/dynotx/liminal-orm/blob/main/liminal/orm/base_model.py)
 
 Below is an example of a custom entity schema defined in code. The properties defined in the `SchemaProperties` object and for `Column` objects
 align with the properties shown on the Benchling website. This is how Liminal defines your Benchling entity schema in code. Any of these properties
@@ -129,4 +129,18 @@ class Pizza(BaseModel, CustomEntityMixin):
 
 ## Validators ([class]<https://github.com/dynotx/liminal-orm/blob/main/liminal/validation/__init__.py>)
 
-As seen in the example above, the `get_validators` method is used to define a list of validators for the entity schema. The `BenchlingValidator` object is used to define the validation objects for the entity schema, and run on entities of the schema. Refer to the [Validators](./validators.md) page to learn more about the different types of validators.
+As seen in the example above, the `get_validators` method is used to define a list of validators for the entity schema. These validators run on entities of the schema that are queried from Benchling's Postgres database. For example:
+
+```python
+pizza_entity = Pizza.query(session).first()
+
+# Validate a single entity from a query
+report = CookTempValidator().validate(pizza_entity)
+
+# Validate all entities for a schema
+reports = Pizza.validate(session)
+```
+
+The list of validators within `get_validators` are used to run on all entities of the schema.
+
+The `BenchlingValidator` object is used to define the validator classes, that can be defined with custom logic to validate entities of a schema. Refer to the [Validators](./validators.md) page to learn more about how to define validators.

docs/reference/operations.md

@@ -1,4 +1,4 @@
-## Operations ([class](https://github.com/dynotx/liminal-orm/blob/main/liminal/base/base_operation.py))
+## Operations: [class](https://github.com/dynotx/liminal-orm/blob/main/liminal/base/base_operation.py)
 
 Operations are the building blocks of a revision file. They represent a singular API call that does a specific action to change the Benchling model. They are generated by the `liminal autogenerate` command in the upgrade/downgrade functions of a revision file and can also be created manually. Operations are used to create, update, and archive entity schemas, dropdowns, and entity schema fields (a full list of operations can be found below). Operations have a couple of common functionalities:
 

docs/reference/validators.md

@@ -0,0 +1,23 @@
+## Benchling Base Validator: [class](https://github.com/dynotx/liminal-orm/blob/main/liminal/validation/__init__.py)
+
+Below is an example of a Benchling Validator defined in Liminal for validating the cook temp of a pizza.
+
+```python
+from liminal.validation import BenchlingValidator, BenchlingValidatorReport, BenchlingReportLevel
+from liminal.orm.base_model import BaseModel
+
+class CookTempValidator(BenchlingValidator):
+    """Validates that a field value is a valid enum value for a Benchling entity"""
+
+    def validate(self, entity: type[BaseModel]) -> BenchlingValidatorReport:
+        valid = True
+        if entity.cook_time is not None and entity.cook_temp is None:
+            valid = False
+            return self.create_report(valid, BenchlingReportLevel.MED, entity, "Cook temp is required if cook time is set")
+        if entity.cook_time is None and entity.cook_temp is not None:
+            valid = False
+            return self.create_report(valid, BenchlingReportLevel.MED, entity, "Cook time is required if cook temp is set")
+        return self.create_report(valid, BenchlingReportLevel.MED, entity, None)
+```
+
+A `validate(entity)` function is required to be defined in the BenchlingValidator subclass. This function should contain the logic to validate the entity. The function should return a `BenchlingValidatorReport` object, which can be easily created using the `create_report` method.

liminal/connection/benchling_service.py

@@ -27,9 +27,9 @@ class BenchlingService(Benchling):
         The connection object that contains the credentials for the Benchling tenant.
     use_api: bool
         Whether to connect to the Benchling SDK. Requires api_client_id and api_client_secret from the connection object.
-    use_db: bool
+    use_db: bool = False
         Whether to connect to the Benchling Postgres database. Requires warehouse_connection_string from the connection object.
-    use_internal_api: bool
+    use_internal_api: bool = False
         Whether to connect to the Benchling internal API. Requires internal_api_admin_email and internal_api_admin_password from the connection object.
     """