Composite jobs (#349)

## changes

- [x] a composite job class (JobList)
- [x] docking returns a JobList
- [x] ability to confirm a JobList
- [x] ability to cancel a JobList
- [x] ability to watch a JobList
- [x] JobList works nicely with docking
- [x] docking flow using JobList mocked
- [x] LigandSet no longer uses to_dataframe when we simply view it
- [x] removed job.to_dataframe -- use JobList.to_dataframe() instead
- [x] docking no longer calls job.to_dataframe

## screenshots

what a ligandset with many ligands looks like

<img width="576" height="298" alt="Screenshot 2025-11-20 at 3 39 46 PM"
src="https://github.com/user-attachments/assets/c001ab0f-86e6-4392-a98e-637adce57bfd"
/>

what a ligandset with poses for a single ligand looks like

<img width="564" height="288" alt="Screenshot 2025-11-20 at 3 40 07 PM"
src="https://github.com/user-attachments/assets/97668f45-663e-438a-8f46-a081bf5fbddf"
/>

Author: sg-s

.cursor/rules/python.mdc

@@ -47,3 +47,7 @@ When modifying an existing function, make the following changes together:
 - To test a specific function, use `pytest -k --mock` 
 
 
+# Common mistakes
+
+- Using uppercase List instead of lowercase list to annotate the type of a list
+- Using uppercase Dist instead of lowercase dist to annotate the type of a dict

.vscode/settings.json

@@ -34,6 +34,7 @@
         "dateutil",
         "deeporigin",
         "drugability",
+        "dtos",
         "emeq",
         "FMCS",
         "HETATM",
@@ -71,6 +72,7 @@
         "sanitizable",
         "SASA",
         "softcore",
-        "Substruct"
+        "Substruct",
+        "textea"
     ]
 }

Makefile

@@ -58,7 +58,7 @@ docs-deploy:
 mock-server:
 	@echo "Starting mock server..."
 	@source $(CURDIR)/venv/bin/activate && \
-	    python scripts/run_mock_server.py $(if $(PORT),$(PORT),8000) && \
+	    python -m tests.run_mock_server $(if $(PORT),$(PORT),4931) && \
 	    deactivate
 
 

README.md

@@ -10,44 +10,12 @@ Deep Origin from the command line and Python.
 > The `deeporigin` client is under active development. Features
 > may change or be removed.
 
-## Installing
 
-> [!CAUTION]
-> As a best practice, we recommend installing this package in a virtual environment.
+## Documentation
 
-To install this package, run the following:
+Please look at our docs for information on how to install and use this:
 
-```bash
-pip install deeporigin
-```
-
-## Configuration
-
-To run this package outside of a Deep Origin workstation (for example, on your own computer), first you need to configure this package. After installing this package, run the following to configure your organization, replacing `org-id` with the ID of the Deep Origin organization that you would like to work with.
-
-```bash
-deeporigin config set organization_id [org-id]
-```
-
-## Developing
-
-First, download the source code from GitHub:
-
-```bash
-git clone [email protected]:deeporiginbio/deeporigin-client.git
-cd deeporigin-client
-```
-
-Second, run the code below to create a virtual environment and install this package into it. This requires make v4.4 or higher.
-
-```bash
-make install
-```
-
-
-### Automated tests on GitHub Actions
-
-The tests are automatically run on GitHub Actions on every commit to every pull request.
+https://client-docs.deeporigin.io/
 
 ## License
 

conftest.py

@@ -28,7 +28,7 @@ def test_server(pytestconfig):
         yield None
         return
 
-    server = MockServer(port=0)
+    server = MockServer(port=4931)  # Fixed port for test server
     server.start()
     yield server
     server.stop()
@@ -42,7 +42,7 @@ def test_server_url(test_server):
         test_server: The test server fixture.
 
     Yields:
-        Base URL of the test server (e.g., "http://127.0.0.1:12345"), or None if --mock is not passed.
+        Base URL of the test server (e.g., "http://127.0.0.1:4931"), or None if --mock is not passed.
     """
     if test_server is None:
         yield None

docs/dd/tutorial/getting-started.md

@@ -90,11 +90,10 @@ sim = Complex.from_dir(BRD_DATA_DIR)
 
 sim.ligands
 ```
-
-!!! success "Expected output"
-
-    ![](../../images//ligands.png)
+and you should see something similar to:
 
+<div style='width: 500px; padding: 15px; border: 1px solid #ddd; border-radius: 6px; background-color: #f9f9f9;'><h3 style='margin-top: 0; color: #333;'>LigandSet with 8 ligands</h3><p style='margin: 8px 0;'><strong>8</strong> unique SMILES</p><p style='margin: 8px 0;'>Properties: initial_smiles, r_exp_dg</p><div style='margin-top: 12px; padding-top: 12px; border-top: 1px solid #ddd;'><p style='margin: 4px 0; font-size: 0.9em; color: #666;'><em>Use <code>.to_dataframe()</code> to convert to a dataframe, <code>.show_df()</code> to view dataframewith structures, or <code>.show()</code> for 3D visualization</em></p></div></div>
+
 
 !!! tip "Jupyter notebooks"
     It is assumed that you are working in a Jupyter notebook (or similar IPython environment). This makes it easier to run the workflow, and some functions assume that you are in a Jupyter notebook.

docs/dev/mock-server.md

@@ -4,7 +4,7 @@ The mock server is a local test server that mimics the DeepOrigin Platform API.
 
 ## Overview
 
-The mock server (`tests/mock_server.py`) provides mock responses for all API endpoints used by the DeepOriginClient. It runs locally using FastAPI and uvicorn, and serves responses based on fixture data stored in `tests/fixtures/`.
+The mock server (`tests/mock_server/`) provides mock responses for all API endpoints used by the DeepOriginClient. It runs locally using FastAPI and uvicorn, and serves responses based on fixture data stored in `tests/fixtures/`.
 
 ## Running the Mock Server
 
@@ -13,21 +13,21 @@ The mock server (`tests/mock_server.py`) provides mock responses for all API end
 To run the mock server standalone for local development:
 
 ```bash
-python scripts/run_mock_server.py [PORT]
+python tests/run_mock_server.py [PORT]
 ```
 
 Where `PORT` is the port number to run the server on (default: 8000).
 
 Example:
 
 ```bash
-python scripts/run_mock_server.py 8000
+python tests/run_mock_server.py 4931
 ```
 
 The server will start and display:
 
 ```bash
-Mock server running at http://127.0.0.1:8000
+Mock server running at http://127.0.0.1:4931
 Press Ctrl+C to stop...
 ```
 
@@ -41,7 +41,7 @@ The mock server is automatically started when running tests with the `--mock` fl
 pytest --mock
 ```
 
-This starts the server for the duration of the test session and automatically stops it when tests complete.
+This starts the server for the duration of the test session and automatically stops it when tests complete. The test server runs on **port 4931** (configured in `conftest.py`).
 
 ## Configuring Your Client
 
@@ -53,7 +53,7 @@ from deeporigin.platform.client import DeepOriginClient
 client = DeepOriginClient(
     token="test-token",  # Any token works with the mock server
     org_key="deeporigin",  # Use any org_key
-    base_url="http://127.0.0.1:8000",  # Mock server URL
+    base_url="http://127.0.0.1:4931",  # Mock server URL (port 4931 for tests)
     env="local",
 )
 ```
@@ -80,12 +80,14 @@ The mock server uses fixture files from `tests/fixtures/` to provide realistic r
 
 ## Extending the Mock Server
 
-To add new endpoints or modify existing ones, edit `tests/mock_server.py`:
+To add new endpoints or modify existing ones, edit `tests/mock_server/server.py`:
 
 1. Add a new route handler in the `_setup_routes()` method
 2. Optionally add fixture files in `tests/fixtures/` if you need realistic data
 3. Use `_load_fixture()` to load JSON fixtures
 
+For file-related endpoints, add them to `tests/mock_server/routers/files.py`.
+
 Example:
 
 ```{.python notest}

docs/how-to/auth.md

@@ -6,22 +6,19 @@
 To use most of the functionality of the Python client, you must first run the following commands to sign into Deep Origin.
 
 
-
-
-
 ```{.python notest}
 from deeporigin import auth
-auth.authenticate()
+_ = auth.get_tokens()
 ```
 
-You will be presented with a prompt similar to below:
+When you first do this, you will be presented with a prompt similar to below:
 
 ```shell
 To connect to the Deep Origin OS, navigate your browser to 
 
-https://<env>auth0.com/activate?user_code=VMPZ-PQFG
+https://<env>auth0.com/activate?user_code=<code>
 
-and verify the confirmation code is "VMPZ-PQFG", and click the "Confirm" button.
+and verify the confirmation code is the one shown, and click the "Confirm" button.
 ```
 
 When you visit that URL, you will see a prompt that looks like:
@@ -36,8 +33,6 @@ After signing in, your access tokens will be cached to disk and then automatical
 be used in subsequent interactions with Deep Origin.
 
 !!! info "Authenticating"
-    In most cases, you only need to authenticate to the Deep Origin OS once.
+    You only need to authenticate to the Deep Origin OS once.
     You do not need to authenticate every time you use the client.
 
-!!! question "Authenticating on Deep Origin workstations"
-    Presently, workstation users must authenticate (once) to the Deep Origin OS. We plan to develop the capability to automatically authenticate workstation users.