docs: initial SDK documentation (#3)

* feat: 1st docs iteration

* feat: add dependency group + CI pipelines

* fix: remove rules and pages

* fix: gitlab template

* Delete .gitlab-ci.yml

* feat: mkdocs workflow

* fix: dir

* fix: update lock

* fix: update lock

* fix: update type

Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>

* feat: add init file

* fix: change mkdocs site/repo url to github

* fix: syntax error in docs

* fix: add RGB convert into README

* Update mkdocs.yml

Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

* Apply suggestion from @matejpekar

* Apply suggestion from @matejpekar

---------

Co-authored-by: JiriStipek <567776@muni.cz>
Co-authored-by: gemini-code-assist[bot] <176961590+gemini-code-assist[bot]@users.noreply.github.com>
Co-authored-by: coderabbitai[bot] <136622811+coderabbitai[bot]@users.noreply.github.com>

Author: 4 people

.github/workflows/mkdocs-build.yml

@@ -0,0 +1,11 @@
+name: MkDocs Build (RationAI Standard)
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    types: [opened, synchronize, reopened]
+
+jobs:
+  run:
+    uses: RationAI/.github/.github/workflows/mkdocs-build.yml@main

README.md

@@ -21,7 +21,7 @@ from PIL import Image
 client = rationai.Client()
 
 # Load an image
-image = Image.open("path/to/image.jpg")
+image = Image.open("path/to/image.jpg").convert("RGB")
 
 # Classify the image
 result = client.models.classify_image("model-name", image)
@@ -58,6 +58,7 @@ asyncio.run(main())
 Classify an image using the specified model.
 
 **Parameters:**
+
 - `model`: The name of the model to use for classification
 - `image`: The image to classify (must be uint8 RGB image)
 - `timeout`: Optional timeout for the request (defaults to 100 seconds)
@@ -69,20 +70,21 @@ Classify an image using the specified model.
 Segment an image using the specified model.
 
 **Parameters:**
+
 - `model`: The name of the model to use for segmentation
 - `image`: The image to segment (must be uint8 RGB image)
 - `timeout`: Optional timeout for the request (defaults to 100 seconds)
 
 **Returns:** Segmentation mask as numpy array with shape `(num_classes, height, width)`
 
-
 ### Slide (`client.slide`)
 
 #### `heatmap(model: str, slide_path: str, tissue_mask_path: str, output_path: str, stride_fraction: float = 0.5, output_bigtiff_tile_height: int = 512, output_bigtiff_tile_width: int = 512, timeout: int = 1000) -> str`
 
 Generate a heatmap for a whole slide image using the specified model.
 
 **Parameters:**
+
 - `model`: The name of the model to use for heatmap generation
 - `slide_path`: Path to the whole slide image
 - `tissue_mask_path`: Path to the tissue mask for the slide
@@ -101,6 +103,7 @@ Generate a heatmap for a whole slide image using the specified model.
 Check quality of a whole slide image.
 
 **Parameters:**
+
 - `wsi_path`: Path to the whole slide image
 - `output_path`: Directory to save output masks
 - `config`: Optional `SlideCheckConfig` for the quality check
@@ -113,6 +116,7 @@ Check quality of a whole slide image.
 Check quality of multiple slides concurrently.
 
 **Parameters:**
+
 - `wsi_paths`: List of paths to whole slide images
 - `output_path`: Directory to save output masks
 - `config`: Optional `SlideCheckConfig` for the quality check
@@ -126,6 +130,7 @@ Check quality of multiple slides concurrently.
 Generate a QC report from processed slides.
 
 **Parameters:**
+
 - `backgrounds`: List of paths to background (slide) images
 - `mask_dir`: Directory containing generated masks
 - `save_location`: Path where the report HTML will be saved
@@ -148,16 +153,16 @@ import rationai
 
 async def process_images_with_semaphore(image_paths, model_name, max_concurrent):
     semaphore = asyncio.Semaphore(max_concurrent)
-    
+
     async def bounded_segment(client, path):
         async with semaphore:
-            image = load_image(path)
+            image = Image.open(path).convert("RGB")
             return await client.models.segment_image(model_name, image)
-    
+
     async with rationai.AsyncClient() as client:
         tasks = [bounded_segment(client, path) for path in image_paths]
         results = await asyncio.gather(*tasks)
-    
+
     return results
 
 # Process up to 16 images concurrently
@@ -174,16 +179,16 @@ from rationai import AsyncClient
 
 async def process_with_as_completed(image_paths, model_name, max_concurrent):
     semaphore = asyncio.Semaphore(max_concurrent)
-    
+
     async def bounded_request(client, path):
         async with semaphore:
-            image = load_image(path)
+            image = Image.open(path).convert("RGB")
             return path, await client.models.segment_image(model_name, image)
-    
+
     async with AsyncClient(models_base_url="http://localhost:8000") as client:
-        tasks = {asyncio.create_task(bounded_request(client, path)): path 
+        tasks = {asyncio.create_task(bounded_request(client, path)): path
                  for path in image_paths}
-        
+
         for future in asyncio.as_completed(tasks):
             path, result = await future
             print(f"Processed {path}")
@@ -192,7 +197,6 @@ async def process_with_as_completed(image_paths, model_name, max_concurrent):
 asyncio.run(process_with_as_completed(image_paths, "model-name", max_concurrent=16))
 ```
 
-
 Start with a conservative limit and monitor server resources to find the optimal value for your setup.
 
 ## Configuration

docs/index.md

@@ -0,0 +1,44 @@
+# RationAI Python SDK
+
+Python SDK for interacting with RationAI pathology image analysis services (classification, segmentation, and QC).
+
+[Quick start](learn/get-started/quick-start.md)
+
+[How it works](learn/how-it-works.md)
+
+[API reference](reference/client.md)
+
+## What you can do
+
+- Run image classification and segmentation via `client.models`.
+- Run quality-control workflows via `client.qc`.
+- Choose sync (`Client`) or async (`AsyncClient`) depending on your app.
+
+## Minimal examples
+
+### Model example
+
+```python
+from PIL import Image
+
+import rationai
+
+image = Image.open("path/to/image.jpg").convert("RGB")
+
+with rationai.Client() as client:
+	result = client.models.classify_image("model-name", image)
+	print(result)
+```
+
+### QC example
+
+```python
+import rationai
+
+with rationai.Client() as client:
+	xopat_url = client.qc.check_slide(
+		wsi_path="/data/slides/slide.svs",
+		output_path="/data/qc-output/slide-001",
+	)
+	print(xopat_url)
+```

docs/learn/get-started/quick-start.md

@@ -0,0 +1,173 @@
+# Quick start
+
+## Sync vs Async clients
+
+This SDK provides two clients:
+
+- `rationai.Client` (sync): Uses blocking HTTP requests. Best for scripts, notebooks, CLIs, or when your code is already synchronous.
+- `rationai.AsyncClient` (async): Uses non-blocking HTTP requests (`await`). Best when you already have an `asyncio` event loop (FastAPI, async workers) or you want to run many requests concurrently.
+
+Both clients expose the same high-level resources:
+
+- `client.models` for image classification/segmentation
+- `client.qc` for quality control endpoints
+
+### What’s the actual difference?
+
+- **Sync** calls (e.g. `client.models.classify_image(...)`) block the current thread until the request completes.
+- **Async** calls (e.g. `await client.models.classify_image(...)`) yield control back to the event loop while the network request is in flight, so other tasks can run.
+
+### Lifecycle (important)
+
+- Prefer using context managers so connections are closed:
+  - sync: `with rationai.Client(...) as client: ...`
+  - async: `async with rationai.AsyncClient(...) as client: ...`
+- If you don’t use `with`, call `client.close()` (sync) / `await client.aclose()` (async).
+
+For details on what is sent over the wire (compression, payloads), see: [How it works](../how-it-works.md).
+
+## API at a glance
+
+### Models
+
+#### `client.models.classify_image`
+
+Signature:
+
+`classify_image(model: str, image: PIL.Image.Image | numpy.typing.NDArray[numpy.uint8], timeout=...) -> float | dict[str, float]`
+
+- `model`: Model name / path appended to `models_base_url`.
+- `image`: **uint8 RGB** image (PIL or NumPy array of shape `(H, W, 3)`).
+- `timeout`: Optional request timeout (defaults to the client’s timeout).
+- Returns: classification result from JSON (often `float` for binary, or `dict[class, prob]`).
+
+#### `client.models.segment_image`
+
+Signature:
+
+`segment_image(model: str, image: PIL.Image.Image | numpy.typing.NDArray[numpy.uint8], timeout=...) -> numpy.typing.NDArray[numpy.float16]`
+
+- `model`: Model name / path appended to `models_base_url`.
+- `image`: **uint8 RGB** image (PIL or NumPy array of shape `(H, W, 3)`).
+- `timeout`: Optional request timeout (defaults to the client’s timeout).
+- Returns: `float16` NumPy array with shape `(num_classes, height, width)`.
+
+### Quality control (QC)
+
+#### `client.qc.check_slide`
+
+Signature:
+
+`check_slide(wsi_path: os.PathLike[str] | str, output_path: os.PathLike[str] | str, config: SlideCheckConfig | None = None, timeout=3600) -> str`
+
+- `wsi_path`: Path to a whole-slide image (evaluated by the QC service).
+- `output_path`: Directory where the QC service should write masks (evaluated by the QC service).
+- `config`: Optional `SlideCheckConfig` (see reference types).
+- `timeout`: Request timeout (default is 3600 seconds).
+- Returns: xOpat URL as plain text.
+
+#### `client.qc.generate_report`
+
+Signature:
+
+`generate_report(backgrounds: Iterable[os.PathLike[str] | str], mask_dir: os.PathLike[str] | str, save_location: os.PathLike[str] | str, compute_metrics: bool = True, timeout=...) -> None`
+
+- `backgrounds`: Iterable of slide/background image paths.
+- `mask_dir`: Directory containing generated masks.
+- `save_location`: Path where the report HTML should be written.
+- `compute_metrics`: Whether to compute aggregated metrics (default: `True`).
+- Returns: nothing.
+
+## Synchronous client
+
+```python
+from PIL import Image
+import rationai
+
+image = Image.open("path/to/image.jpg").convert("RGB")
+
+with rationai.Client() as client:
+    result = client.models.classify_image("model-name", image)
+    print(result)
+```
+
+## Asynchronous client
+
+```python
+import asyncio
+from PIL import Image
+import rationai
+
+image = Image.open("path/to/image.jpg").convert("RGB")
+
+async def main():
+    async with rationai.AsyncClient() as client:
+        result = await client.models.classify_image("model-name", image)
+        print(result)
+
+asyncio.run(main())
+```
+
+### Concurrency with the async client
+
+Use `asyncio` concurrency when you need to process many images. A semaphore is the simplest way to cap concurrency so you don’t overload the server.
+
+```python
+import asyncio
+from PIL import Image
+import rationai
+
+async def classify_many(paths: list[str], model: str, *, max_concurrent: int = 8) -> list[float | dict[str, float]]:
+    sem = asyncio.Semaphore(max_concurrent)
+
+    async def one(client: rationai.AsyncClient, path: str) -> float | dict[str, float]:
+        async with sem:
+            image = Image.open(path).convert("RGB")
+            return await client.models.classify_image(model, image)
+
+    async with rationai.AsyncClient() as client:
+        return await asyncio.gather(*(one(client, p) for p in paths))
+```
+
+## Common pitfalls
+
+- **PIL image mode**: ensure RGB.
+
+```python
+image = Image.open(path).convert("RGB")
+```
+
+- **NumPy dtype/shape**: the services expect `uint8` RGB images.
+
+```python
+import numpy as np
+
+assert arr.dtype == np.uint8
+assert arr.ndim == 3 and arr.shape[2] == 3
+```
+
+- **Forgetting to close clients**: prefer `with ...` / `async with ...`.
+
+- **Too much async concurrency**: cap with a semaphore (start small like 4–16) to avoid server overload/timeouts.
+
+- **Timeouts**: segmentation/QC can take longer. Increase per-request timeout if needed.
+
+```python
+result = client.models.segment_image("model", image, timeout=300)
+```
+
+- **QC paths are server-side**: `wsi_path` / `output_path` must exist where the QC service runs.
+
+## Configuration
+
+You can override service URLs and timeouts:
+
+```python
+from rationai import Client
+
+client = Client(
+    models_base_url="http://localhost:8000",
+    qc_base_url="http://localhost:8001",
+    timeout=300,
+)
+```