Merge pull request #24 from FocoosAI/feat/mkdocs

add mkdocs documentation

.github/workflows/release.yml

@@ -49,3 +49,27 @@ jobs:
           name: Release ${{ steps.tag_version.outputs.new_tag }}
           body: ${{ steps.tag_version.outputs.changelog }}
           generateReleaseNotes: true
+  mkdocs:
+    runs-on: ubuntu-22.04
+    needs: release
+    permissions:
+      contents: write
+    steps:
+      - uses: actions/checkout@v4
+      - name: Setup Python
+        uses: actions/setup-python@v4
+        with:
+          python-version:  3.12
+      - name: Install the latest version of uv and set the python version to 3.12
+        uses: astral-sh/setup-uv@v4
+        with:
+          python-version:  3.12
+      - name: Install dependencies
+        run: uv pip install .[docs]
+      - name: Build mkdocs site
+        run: mkdocs build --clean
+      - name: Deploy to GitHub Pages
+        uses: peaceiris/actions-gh-pages@v3
+        with:
+          github_token: ${{ secrets.GITHUB_TOKEN }}
+          publish_dir: ./site

.pre-commit-config.yaml

@@ -7,6 +7,8 @@ repos:
       - id: check-ast
       - id: check-toml
       - id: check-yaml
+        args:
+        -   --unsafe
       #- id: check-json
       - id: check-case-conflict
       - id: check-merge-conflict

README.md

@@ -56,7 +56,6 @@ from focoos import Focoos
 focoos = Focoos(api_key=os.getenv("FOCOOS_API_KEY"))
 
 model = focoos.get_remote_model("focoos_object365")
-model.deploy()
 detections = model.infer("./image.jpg", threshold=0.4)
 ```
 

docs/api/focoos.md

@@ -0,0 +1 @@
+::: focoos.focoos

docs/api/local_model.md

@@ -0,0 +1 @@
+::: focoos.local_model

docs/api/remote_model.md

@@ -0,0 +1 @@
+::: focoos.remote_model

docs/api/runtime.md

@@ -0,0 +1 @@
+::: focoos.runtime

docs/assets/stylesheets/custom.css

@@ -0,0 +1,22 @@
+/* Light mode (default scheme) */
+[data-md-color-scheme="default"] {
+    --md-primary-fg-color: #63dca7;
+    --md-primary-bg-color: #000000;
+    --md-accent-fg-color: #025ee6;
+    --md-typeset-a-color: #025ee6;
+}
+[data-md-color-scheme=slate][data-md-color-primary=indigo] {
+    --md-typeset-a-color: #63dca7;
+}
+/* Dark mode (slate scheme) */
+[data-md-color-scheme="slate"] {
+    --md-primary-fg-color: #025ee6;
+    --md-primary-bg-color: #000000;
+    --md-accent-fg-color: #63dca7;
+    --md-typeset-a-color: #63dca7;
+}
+
+/* Override the first child of md-header__topic */
+.md-header__topic:first-child {
+    font-weight: 350;  /* Adjust to a normal font weight, 400 or another value */
+}

docs/datasets.md

@@ -0,0 +1,28 @@
+# Datasets
+
+With the Focoos SDK, you can leverage a diverse collection of foundational datasets specifically tailored for computer vision tasks. These datasets, spanning tasks such as segmentation, detection, and instance segmentation, provide a strong foundation for building and optimizing models across a variety of domains.
+
+---
+
+Datasets:
+
+| Name                 | Task       | Description                                                             | Layout            |
+|----------------------|------------|-------------------------------------------------------------------------|-------------------|
+| Aeroscapes           | semseg     | A drone dataset to recognize many classes!                               | supervisely       |
+| Blister              | instseg    | A dataset to find blisters                                               | roboflow_coco     |
+| Boxes                | detection  | Finding different boxes on the conveyor belt                             | roboflow_coco     |
+| Cable                | detection  | A dataset for detecting damages in cables (from Roboflow 100) - <https://universe.roboflow.com/roboflow-100/cable-damage/dataset/2#> | roboflow_coco     |
+| Circuit dataset      | detection  | A dataset with electronic circuits                                       | roboflow_coco     |
+| Concrete             | instseg    | A dataset to find defect in concrete                                     | roboflow_coco     |
+| Crack Segmentation   | instseg    | A dataset for segmenting cracks in buildings with 4k images.              | roboflow_coco     |
+| Football-detection   | detection  | Football-detection by Roboflow                                           | roboflow_coco     |
+| Peanuts              | detection  | Finding Molded or non Molded Peanuts                                     | roboflow_coco     |
+| Strawberries         | instseg    | Finding defects on strawberries                                          | roboflow_coco     |
+| aquarium             | detection  | aquarium                                                                | roboflow_coco     |
+| bottles              | detection  | bottles                                                                 | roboflow_coco     |
+| chess_pieces         | detection  | A chess detector dataset by roboflow <https://universe.roboflow.com/roboflow-100/chess-pieces-mjzgj> | roboflow_coco     |
+| coco_2017_det        | detection  | COCO Detection                                                           | catalog           |
+| halo                 | detection  | Halo fps by Roboflow                                                    | roboflow_coco     |
+| lettuce              | detection  | A dataset to find lettuce                                                | roboflow_coco     |
+| safety               | detection  | From roboflow Universe: <https://universe.roboflow.com/roboflow-100/construction-safety-gsnvb> | roboflow_coco     |
+| screw                | detection  | Screw by Roboflow                                                       | roboflow_coco     |

docs/development/changelog.md

@@ -0,0 +1 @@
+{% include-markdown "helpers/wip.md" %}

docs/development/code_of_conduct.md

@@ -0,0 +1 @@
+{% include-markdown "helpers/wip.md" %}

docs/development/contributing.md

@@ -0,0 +1 @@
+{% include-markdown "helpers/wip.md" %}

docs/getting_started/installation.md

@@ -0,0 +1,48 @@
+# Installation
+
+The focoos SDK provides flexibility for installation based on the execution environment you plan to use. The package supports `CPU`, `NVIDIA GPU`, and `NVIDIA GPU with TensorRT` environments. Please note that only one execution environment should be selected during installation.
+
+## Requirements
+
+For **local inference**, ensure that you have CUDA 12 and cuDNN 9 installed, as they are required for onnxruntime version 1.20.1.
+
+To install cuDNN 9:
+
+```bash linenums="0"
+apt-get -y install cudnn9-cuda-12
+```
+
+To perform inference using TensorRT, ensure you have TensorRT version 10.5 installed.
+
+## Installation Options
+
+* CPU Environment
+
+If you plan to run the SDK on a CPU-only environment:
+
+```bash linenums="0"
+pip install 'focoos[cpu] @ git+https://github.com/FocoosAI/focoos.git'
+```
+
+* NVIDIA GPU Environment
+
+For execution using NVIDIA GPUs (with ONNX Runtime GPU support):
+
+```bash linenums="0"
+pip install 'focoos[gpu] @ git+https://github.com/FocoosAI/focoos.git'
+```
+
+* NVIDIA GPU with TensorRT
+
+For optimized execution using NVIDIA GPUs with TensorRT:
+
+```bash linenums="0"
+pip install 'focoos[tensorrt] @ git+https://github.com/FocoosAI/focoos.git'
+```
+
+!!! note
+    🛠️ **Installation Tip:** If you want to install a specific version, for example `v0.1.3`, use:
+    ```bash
+    pip install 'focoos[tensorrt] @ git+https://github.com/FocoosAI/[email protected]'
+    ```
+    📋 **Check Versions:** Visit [https://github.com/FocoosAI/focoos/tags](https://github.com/FocoosAI/focoos/tags) for available versions.

docs/getting_started/introduction.md

@@ -0,0 +1,7 @@
+# Focoos Python SDK 📦
+
+Unlock the full potential of Focoos AI with the Focoos Python SDK! 🚀 This powerful SDK gives you seamless access to our cutting-edge computer vision models and tools, allowing you to effortlessly interact with the Focoos API. With just a few lines of code, you can easily **select, customize, test, and deploy** pre-trained models tailored to your specific needs. Whether you're deploying in the cloud or on edge devices, the Focoos Python SDK integrates smoothly into your workflow, speeding up your development process.
+
+Ready to dive in? Get started with the setup in just a few simple steps!
+
+[🚀 Install the Focoos Python SDK](../installation)

docs/getting_started/quickstart.md

@@ -0,0 +1,28 @@
+# Quickstart 🚀
+
+Getting started with Focoos AI has never been easier! In just a few steps, you can quickly set up remote inference using our built-in models. Here's a simple example of how to perform object detection with the **focoos_object365** model:
+
+## Step 1: Install the SDK
+
+First, make sure you've installed the Focoos Python SDK by following the [installation guide](../installation).
+
+## Step 2: Set Up Remote Inference
+
+With the SDK installed, you can start using the Focoos API to run inference remotely. Here's a basic code snippet to detect objects in an image using a pre-trained model:
+
+```python
+from focoos import Focoos
+import os
+
+# Initialize the Focoos client with your API key
+focoos = Focoos(api_key=os.getenv("FOCOOS_API_KEY"))
+
+# Get the remote model (focoos_object365) from Focoos API
+model = focoos.get_remote_model("focoos_object365")
+
+# Run inference on an image
+detections = model.infer("./image.jpg", threshold=0.4)
+
+# Output the detections
+print(detections)
+```

docs/helpers/wip.md

@@ -0,0 +1,7 @@
+🚧 **Work in Progress** 🚧
+
+This page is currently being developed and may not be complete.
+
+---
+
+Feel free to contribute to this page! If you have suggestions or would like to help improve it, please [contact us](mailto:[email protected]).

docs/how_to/cloud_training.md

@@ -0,0 +1,77 @@
+# Cloud Training
+
+This section covers the steps to train a model in the cloud using the `focoos` library. The following example demonstrates how to interact with the Focoos API to manage models, datasets, and training jobs.
+
+---
+
+## Listing Available Datasets
+
+Before training a model, you can list all available shared datasets:
+
+```python
+from pprint import pprint
+import os
+from focoos import Focoos
+
+focoos = Focoos(api_key=os.getenv("FOCOOS_API_KEY"))
+
+datasets = focoos.list_shared_datasets()
+pprint(datasets)
+```
+
+##  Initiating a Cloud Training Job
+
+To start training, configure the model, dataset, and training parameters as shown below:
+
+```python
+from focoos.ports import Hyperparameters, TrainInstance
+
+model = focoos.get_remote_model("<YOUR-MODEL-ID>")
+
+res = model.train(
+    anyma_version="0.11.1",
+    dataset_ref="<YOUR-DATASET-ID>",
+    instance_type=TrainInstance.ML_G4DN_XLARGE,
+    volume_size=50,
+    max_runtime_in_seconds=36000,
+    hyperparameters=Hyperparameters(
+        learning_rate=0.0001,
+        batch_size=16,
+        max_iters=1500,
+        eval_period=100,
+        resolution=640,
+    ),  # type: ignore
+)
+pprint(res)
+```
+
+##  Monitoring Training Progress
+
+Once the training job is initiated, monitor its progress by polling the training status. Use the following code:
+
+```python
+import time
+from pprint import pprint
+from focoos.utils.logger import get_logger
+
+completed_status = ["Completed", "Failed"]
+logger = get_logger(__name__)
+
+model = focoos.get_remote_model("<YOUR-MODEL-ID>")
+status = model.train_status()
+
+while status["main_status"] not in completed_status:
+    status = model.train_status()
+    logger.info(f"Training status: {status['main_status']}")
+    pprint(f"Training progress: {status['status_transitions']}")
+    time.sleep(30)
+```
+
+##  Retrieving Training Logs
+
+After the training process is complete, retrieve the logs for detailed insights:
+
+```python
+logs = model.train_logs()
+pprint(logs)
+```

docs/how_to/inference.md

@@ -0,0 +1,40 @@
+# Inferece
+
+This section covers how to perform inference using the `focoos` library. You can deploy models to the cloud for predictions, integrate with Gradio for interactive demos, or run inference locally.
+
+---
+
+## 🤖 Cloud Inference
+
+```python
+from focoos import Focoos
+
+focoos = Focoos(api_key=os.getenv("FOCOOS_API_KEY"))
+
+model = focoos.get_remote_model("focoos_object365")
+detections = model.infer("./image.jpg", threshold=0.4)
+```
+
+## 🤖 Cloud Inference with Gradio
+
+setup `FOCOOS_API_KEY_GRADIO` environment variable with your Focoos API key
+
+```bash linenums="0"
+pip install '.[gradio]'
+```
+
+```bash linenums="0"
+python gradio/app.py
+```
+
+## 🤖 Local Inference
+
+```python
+from focoos import Focoos
+
+focoos = Focoos(api_key=os.getenv("FOCOOS_API_KEY"))
+
+model = focoos.get_local_model("focoos_object365")
+
+detections = model.infer("./image.jpg", threshold=0.4)
+```