Skip to content

cli

Focoos Command Line Interface.

The Focoos CLI provides both Typer-style commands and a streamlined interface for computer vision tasks.

This module contains the main CLI application with commands for training, validation, prediction, export, benchmarking, and system utilities.

Usage 
1
focoos COMMAND [OPTIONS]
Available Commands
  • train: Train a model on a dataset
  • val: Validate a model on a dataset
  • predict: Run inference on images
  • export: Export a model to different formats
  • benchmark: Benchmark model performance
  • version: Show Focoos version information
  • checks: Run system checks and display system information
  • settings: Show current Focoos configuration settings
  • hub: Focoos Hub commands

Examples:

Training a model: 

1
focoos train --model fai-detr-m-coco --dataset mydataset.zip --im-size 640

Running inference: 

1
focoos predict --model fai-detr-m-coco --source image.jpg --im-size 640

Validating a model: 

1
focoos val --model fai-detr-m-coco --dataset mydataset.zip --im-size 640

Exporting a model: 

1
focoos export --model fai-detr-m-coco --format onnx --im-size 640

Benchmarking performance: 

1
focoos benchmark --model fai-detr-m-coco --iterations 100 --device cuda

System information: 

1
2
3
focoos checks
focoos settings
focoos version

Focoos Hub commands: 

1
2
3
4
5
focoos hub
focoos hub models
focoos hub datasets
focoos hub dataset download --ref my-dataset --path ./data
focoos hub dataset upload --ref my-dataset --path ./data.zip

Note

For command-specific help, use: focoos COMMAND --help

See Also

benchmark(model, im_size=None, iterations=None, device='cuda') #

Benchmark model performance with detailed metrics.

This command performs comprehensive performance benchmarking of a model, measuring inference speed, memory usage, and throughput across multiple iterations. Provides detailed statistics including mean, median, and percentile measurements for performance analysis.

Benchmark Metrics
  • Inference Time: Per-image processing time (ms)
  • Throughput: Frames per second (FPS)
  • Memory Usage: Peak GPU/CPU memory consumption
  • Latency Statistics: P50, P95, P99 percentiles
  • Model Loading Time: Initialization overhead
  • Warmup Performance: Cold vs. warm inference speeds
Performance Factors
  • Image Size: Larger images → slower inference
  • Model Complexity: More parameters → higher latency
  • Device Type: GPU vs. CPU performance differences
  • Batch Size: Single vs. batch inference comparison
  • Runtime Backend: ONNX vs. PyTorch performance

Parameters:

Name Type Description Default
model str

Name of the model or path to model file for benchmarking. Can be specified in several ways: - Pretrained model: Simple model name like 'fai-detr-m-coco' - Hub model: Format 'hub://' for models from Focoos Hub - Local model: Model name with --models-dir pointing to custom directory - Default directory model: Model name for models in default Focoos directory

 required
im_size Optional[int]

Input image size for benchmarking. If not specified, uses the model's default input size. Larger sizes typically result in slower inference but may improve accuracy.

 None
iterations Optional[int]

Number of benchmark iterations to run. If not specified, uses a default number of iterations suitable for reliable statistics. More iterations provide more accurate timing measurements.

 None
device str

Device to use for benchmarking ('cuda' or 'cpu'). Defaults to 'cuda'. GPU benchmarking typically shows better performance but requires CUDA availability.

 'cuda'

Examples:

Basic benchmarking with pretrained model: 

1
focoos benchmark --model fai-detr-m-coco

Benchmark model from Focoos Hub: 

1
focoos benchmark --model hub://<model-ref> --iterations 100

Benchmark local model from custom directory: 

1
focoos benchmark --model my-model --models-dir ./custom_models --im-size 640

Benchmark local model from default Focoos directory: 

1
focoos benchmark --model my-exported-model --iterations 200

Benchmark with specific parameters: 

1
focoos benchmark --model fai-detr-m-coco --im-size 800 --iterations 100

CPU benchmarking: 

1
focoos benchmark --model fai-detr-m-coco --device cpu --iterations 50

Comprehensive benchmark suite: 

1
2
3
4
# Test different image sizes
focoos benchmark --model fai-detr-m-coco --im-size 416
focoos benchmark --model fai-detr-m-coco --im-size 640
focoos benchmark --model fai-detr-m-coco --im-size 800

Output

The command prints benchmark results to the console:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
Benchmark Results:
==================
Model: fai-detr-m-coco
Device: CUDA (GeForce RTX 3080)
Image Size: 640x640
Iterations: 100

Performance Metrics:
- Average Inference Time: 12.5ms
- Throughput (FPS): 80.0
- P50 Latency: 11.8ms
- P95 Latency: 15.2ms
- P99 Latency: 18.1ms
- Peak GPU Memory: 2.1GB
- Model Loading Time: 1.2s

Raises:

Type Description
AssertionError

If device parameter is not valid.
FileNotFoundError

If model file is not found.
RuntimeError

If device is unavailable or out of memory.
ImportError

If required runtime dependencies are missing.
Note

Benchmark results can vary based on system load, thermal throttling, and hardware specifications. For consistent results, ensure the system is not under heavy load during benchmarking. Results are automatically saved to a benchmark report file for later analysis.

See Also
Source code in focoos/cli/cli.py 
1001
1002
1003
1004
1005
1006
1007
1008
1009
1010
1011
1012
1013
1014
1015
1016
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
1030
1031
1032
1033
1034
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
1053
1054
1055
1056
1057
1058
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
1127
1128
1129
1130
1131
1132
1133
@app.command("benchmark")
def benchmark(
    model: Annotated[str, typer.Option(help="Model name or path (required)")],
    im_size: Annotated[Optional[int], typer.Option(help="Image size for benchmarking")] = None,
    iterations: Annotated[Optional[int], typer.Option(help="Number of benchmark iterations")] = None,
    device: Annotated[str, typer.Option(help="Device for benchmarking (cuda or cpu)")] = "cuda",
):
    """Benchmark model performance with detailed metrics.

    This command performs comprehensive performance benchmarking of a model,
    measuring inference speed, memory usage, and throughput across multiple
    iterations. Provides detailed statistics including mean, median, and
    percentile measurements for performance analysis.

    Benchmark Metrics:
        - **Inference Time**: Per-image processing time (ms)
        - **Throughput**: Frames per second (FPS)
        - **Memory Usage**: Peak GPU/CPU memory consumption
        - **Latency Statistics**: P50, P95, P99 percentiles
        - **Model Loading Time**: Initialization overhead
        - **Warmup Performance**: Cold vs. warm inference speeds

    Performance Factors:
        - **Image Size**: Larger images → slower inference
        - **Model Complexity**: More parameters → higher latency
        - **Device Type**: GPU vs. CPU performance differences
        - **Batch Size**: Single vs. batch inference comparison
        - **Runtime Backend**: ONNX vs. PyTorch performance

    Args:
        model (str): Name of the model or path to model file for benchmarking.
            Can be specified in several ways:
            - **Pretrained model**: Simple model name like 'fai-detr-m-coco'
            - **Hub model**: Format 'hub://<model-ref>' for models from Focoos Hub
            - **Local model**: Model name with --models-dir pointing to custom directory
            - **Default directory model**: Model name for models in default Focoos directory
        im_size (Optional[int]): Input image size for benchmarking. If not specified,
            uses the model's default input size. Larger sizes typically
            result in slower inference but may improve accuracy.
        iterations (Optional[int]): Number of benchmark iterations to run. If not specified,
            uses a default number of iterations suitable for reliable statistics.
            More iterations provide more accurate timing measurements.
        device (str): Device to use for benchmarking ('cuda' or 'cpu'). Defaults to 'cuda'.
            GPU benchmarking typically shows better performance but requires CUDA availability.

    Examples:
        Basic benchmarking with pretrained model:
        ```bash
        focoos benchmark --model fai-detr-m-coco
        ```

        Benchmark model from Focoos Hub:
        ```bash
        focoos benchmark --model hub://<model-ref> --iterations 100
        ```

        Benchmark local model from custom directory:
        ```bash
        focoos benchmark --model my-model --models-dir ./custom_models --im-size 640
        ```

        Benchmark local model from default Focoos directory:
        ```bash
        focoos benchmark --model my-exported-model --iterations 200
        ```

        Benchmark with specific parameters:
        ```bash
        focoos benchmark --model fai-detr-m-coco --im-size 800 --iterations 100
        ```

        CPU benchmarking:
        ```bash
        focoos benchmark --model fai-detr-m-coco --device cpu --iterations 50
        ```

        Comprehensive benchmark suite:
        ```bash
        # Test different image sizes
        focoos benchmark --model fai-detr-m-coco --im-size 416
        focoos benchmark --model fai-detr-m-coco --im-size 640
        focoos benchmark --model fai-detr-m-coco --im-size 800
        ```

    Output:
        The command prints benchmark results to the console:

        ```
        Benchmark Results:
        ==================
        Model: fai-detr-m-coco
        Device: CUDA (GeForce RTX 3080)
        Image Size: 640x640
        Iterations: 100

        Performance Metrics:
        - Average Inference Time: 12.5ms
        - Throughput (FPS): 80.0
        - P50 Latency: 11.8ms
        - P95 Latency: 15.2ms
        - P99 Latency: 18.1ms
        - Peak GPU Memory: 2.1GB
        - Model Loading Time: 1.2s
        ```

    Raises:
        AssertionError: If device parameter is not valid.
        FileNotFoundError: If model file is not found.
        RuntimeError: If device is unavailable or out of memory.
        ImportError: If required runtime dependencies are missing.

    Note:
        Benchmark results can vary based on system load, thermal throttling,
        and hardware specifications. For consistent results, ensure the system
        is not under heavy load during benchmarking. Results are automatically
        saved to a benchmark report file for later analysis.

    See Also:
        - [`focoos predict`][focoos.cli.cli.predict]: For actual inference
        - [`focoos export`][focoos.cli.cli.export]: For optimized model formats
    """
    typer.echo(f"📦 Starting benchmark - Model: {model}, Iterations: {iterations}, Size: {im_size}, Device: {device}")
    try:
        validated_device = cast(DeviceType, device)
        assert device in get_args(DeviceType)
        benchmark_command(
            model_name=model,
            iterations=iterations,
            im_size=im_size,
            device=validated_device,
        )
    except Exception as e:
        typer.echo(f"❌ Benchmark failed: {e}")

checks() #

Run system checks and display system information.

This command performs comprehensive system checks including hardware information, GPU availability, dependencies, and other system-level diagnostics relevant to Focoos operation.

The system checks include
  • Hardware information (CPU, memory, GPU)
  • CUDA availability and version
  • Python environment details
  • Focoos dependencies status
  • System compatibility verification

Examples:

1
focoos checks

Output: 

1
2
3
4
5
6
7
8
9
Running system checks...

System Information:
==================
OS: Linux 5.4.0-74-generic
Python: 3.8.10
CUDA: 11.2.2
GPU: NVIDIA GeForce RTX 3080
Memory: 32GB

Raises:

Type Description
Exit

If system checks fail or encounter errors.
See Also
Source code in focoos/cli/cli.py 
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
@app.command("checks")
def checks():
    """Run system checks and display system information.

    This command performs comprehensive system checks including hardware
    information, GPU availability, dependencies, and other system-level
    diagnostics relevant to Focoos operation.

    The system checks include:
        - Hardware information (CPU, memory, GPU)
        - CUDA availability and version
        - Python environment details
        - Focoos dependencies status
        - System compatibility verification

    Examples:
        ```bash
        focoos checks
        ```

        Output:
        ```
        Running system checks...

        System Information:
        ==================
        OS: Linux 5.4.0-74-generic
        Python: 3.8.10
        CUDA: 11.2.2
        GPU: NVIDIA GeForce RTX 3080
        Memory: 32GB
        ```

    Raises:
        typer.Exit: If system checks fail or encounter errors.

    See Also:
        - [`focoos version`][focoos.cli.cli.version]: For version info only
        - [`focoos settings`][focoos.cli.cli.settings]: For configuration details
    """
    typer.echo("Running system checks...")
    try:
        from focoos.utils.system import get_system_info

        system_info = get_system_info()
        system_info.pprint()
    except Exception as e:
        logger.error(f"Error running checks: {e}")
        raise typer.Exit(1)

export(model, format=ExportFormat.ONNX, output_dir=None, device='cuda', onnx_opset=17, im_size=640, overwrite=False) #

Export a trained model to various deployment formats.

This command exports a Focoos model to different formats suitable for deployment in various environments. Currently supports ONNX and TorchScript formats for flexible deployment across different platforms and frameworks.

Supported Export Formats
  • ONNX: Cross-platform neural network format for interoperability
  • TorchScript: PyTorch's native serialization format for production
Platform Compatibility
Format Linux Windows macOS Mobile Edge Description
ONNX ✅ ✅ ✅ ✅ ✅ Universal format
TorchScript ✅ ✅ ✅ ✅ ✅ PyTorch native

Parameters:

Name Type Description Default
model str

Name of the Focoos model to export (e.g., 'fai-detr-m-coco'). Can be specified in several ways: - Pretrained model: Simple model name like 'fai-detr-m-coco' - Hub model: Format 'hub://' for models from Focoos Hub - Local model: Model name or model directory path (e.g., 'my-model' or '/path/to/my-model') - Default directory model: Model name for models in default Focoos directory

 required
format Optional[ExportFormat]

Target export format. Defaults to ONNX. Available formats: 'onnx', 'torchscript'.

 ONNX
output_dir Optional[str]

Directory to save the exported model files. If not specified, uses a default export directory.

 None
device Optional[str]

Device to use for export process ('cuda' or 'cpu'). Defaults to 'cuda'.

 'cuda'
onnx_opset Optional[int]

ONNX opset version for ONNX exports. Defaults to 17. Higher versions support more operations but may have compatibility issues. Only applies to ONNX format exports.

 17
im_size Optional[int]

Input image size for the exported model. Defaults to 640. This determines the input tensor shape for the exported model.

 640
overwrite Optional[bool]

Whether to overwrite existing exported files. Defaults to False. If False, export will fail if output files already exist.

 False

Examples:

Basic ONNX export with pretrained model: 

1
focoos export --model fai-detr-m-coco

Export model from Focoos Hub: 

1
focoos export --model hub://<model-ref> --format onnx

Export local model from custom directory: 

1
focoos export --model my-fine-tuned-model --models-dir ./trained_models

Export local model from default Focoos directory: 

1
focoos export --model my-checkpoint-model --format torchscript

Export to TorchScript: 

1
focoos export --model fai-detr-m-coco --format torchscript

Export with custom image size: 

1
focoos export --model fai-detr-m-coco --format onnx --im-size 800

Export to custom directory with overwrite: 

1
focoos export --model fai-detr-m-coco --format onnx                       --output-dir ./exported_models --overwrite

CPU-based export: 

1
focoos export --model fai-detr-m-coco --format torchscript                       --device cpu --im-size 416

Raises:

Type Description
AssertionError

If device parameter is not valid.
ValueError

If export format is not supported.
RuntimeError

If export process fails due to model incompatibility.
FileExistsError

If output files exist and overwrite is disabled.
Note

ONNX format provides broader compatibility across different frameworks and deployment environments. TorchScript format is optimized for PyTorch-based deployment scenarios and may offer better performance in PyTorch environments.

See Also
Source code in focoos/cli/cli.py 
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
@app.command("export")
def export(
    model: Annotated[str, typer.Option(help="Model name (required)")],
    format: Annotated[Optional[ExportFormat], typer.Option(help="Export format")] = ExportFormat.ONNX,
    output_dir: Annotated[Optional[str], typer.Option(help="Output directory")] = None,
    device: Annotated[Optional[str], typer.Option(help="Device (cuda or cpu)")] = "cuda",
    onnx_opset: Annotated[Optional[int], typer.Option(help="ONNX opset version")] = 17,
    im_size: Annotated[Optional[int], typer.Option(help="Image size for export")] = 640,
    overwrite: Annotated[Optional[bool], typer.Option(help="Overwrite existing files")] = False,
):
    """Export a trained model to various deployment formats.

    This command exports a Focoos model to different formats suitable for
    deployment in various environments. Currently supports ONNX and TorchScript
    formats for flexible deployment across different platforms and frameworks.

    Supported Export Formats:
        - **ONNX**: Cross-platform neural network format for interoperability
        - **TorchScript**: PyTorch's native serialization format for production

    Platform Compatibility:
        | Format | Linux | Windows | macOS | Mobile | Edge | Description |
        |--------|-------|---------|-------|--------|------|-------------|
        | ONNX   | ✅    | ✅      | ✅    | ✅     | ✅   | Universal format |
        | TorchScript | ✅ | ✅     | ✅    | ✅     | ✅   | PyTorch native |

    Args:
        model (str): Name of the Focoos model to export (e.g., 'fai-detr-m-coco').
            Can be specified in several ways:
            - **Pretrained model**: Simple model name like 'fai-detr-m-coco'
            - **Hub model**: Format 'hub://<model-ref>' for models from Focoos Hub
            - **Local model**: Model name or model directory path (e.g., 'my-model' or '/path/to/my-model')
            - **Default directory model**: Model name for models in default Focoos directory
        format (Optional[ExportFormat]): Target export format. Defaults to ONNX.
            Available formats: 'onnx', 'torchscript'.
        output_dir (Optional[str]): Directory to save the exported model files.
            If not specified, uses a default export directory.
        device (Optional[str]): Device to use for export process ('cuda' or 'cpu').
            Defaults to 'cuda'.
        onnx_opset (Optional[int]): ONNX opset version for ONNX exports. Defaults to 17.
            Higher versions support more operations but may have compatibility issues.
            Only applies to ONNX format exports.
        im_size (Optional[int]): Input image size for the exported model. Defaults to 640.
            This determines the input tensor shape for the exported model.
        overwrite (Optional[bool]): Whether to overwrite existing exported files.
            Defaults to False. If False, export will fail if output files already exist.

    Examples:
        Basic ONNX export with pretrained model:
        ```bash
        focoos export --model fai-detr-m-coco
        ```

        Export model from Focoos Hub:
        ```bash
        focoos export --model hub://<model-ref> --format onnx
        ```

        Export local model from custom directory:
        ```bash
        focoos export --model my-fine-tuned-model --models-dir ./trained_models
        ```

        Export local model from default Focoos directory:
        ```bash
        focoos export --model my-checkpoint-model --format torchscript
        ```

        Export to TorchScript:
        ```bash
        focoos export --model fai-detr-m-coco --format torchscript
        ```

        Export with custom image size:
        ```bash
        focoos export --model fai-detr-m-coco --format onnx --im-size 800
        ```

        Export to custom directory with overwrite:
        ```bash
        focoos export --model fai-detr-m-coco --format onnx \
                      --output-dir ./exported_models --overwrite
        ```

        CPU-based export:
        ```bash
        focoos export --model fai-detr-m-coco --format torchscript \
                      --device cpu --im-size 416
        ```

    Raises:
        AssertionError: If device parameter is not valid.
        ValueError: If export format is not supported.
        RuntimeError: If export process fails due to model incompatibility.
        FileExistsError: If output files exist and overwrite is disabled.

    Note:
        ONNX format provides broader compatibility across different frameworks and
        deployment environments. TorchScript format is optimized for PyTorch-based
        deployment scenarios and may offer better performance in PyTorch environments.

    See Also:
        - [`focoos predict`][focoos.cli.cli.predict]: For using exported models
        - [`focoos benchmark`][focoos.cli.cli.benchmark]: For testing exported models
    """
    typer.echo(
        f"📦 Starting export - Model: {model}, Format: {format}, Output dir: {output_dir}, Device: {device}, ONNX opset: {onnx_opset}, Image size: {im_size}, Overwrite: {overwrite}"
    )
    try:
        validated_device = cast(DeviceType, device)
        assert device in get_args(DeviceType)
        export_command(
            model_name=model,
            format=format,
            output_dir=output_dir,
            device=validated_device,
            onnx_opset=onnx_opset,
            im_size=im_size,
            overwrite=overwrite,
        )
    except Exception as e:
        typer.echo(f"❌ Export failed: {e}")

predict(source, model='fai-detr-l-obj365', runtime=None, im_size=640, conf=0.5, output_dir=PREDICTIONS_DIR, save=True, save_json=True, save_masks=True) #

Run inference on images with flexible output options.

This command performs inference (prediction) on input images using a trained model. Supports various output formats including annotated images, JSON results, and mask files. Results are always printed to the console.

Supported Input
  • Single Images: Local image files (loaded via image_loader())
  • URLs: Remote image files accessible via URL
Output Options
  • Console Output: Detection results printed to terminal (always enabled)
  • Annotated Images: Visual results with bounding boxes and labels (if save=True)
  • JSON Files: Machine-readable detection results with coordinates and confidence (if save_json=True)
  • Mask Images: Individual mask files as PNG images (if save_masks=True and model produces masks)

Parameters:

Name Type Description Default
model str

Name of the model or path to model file for inference. Can be specified in several ways: - Pretrained model: Simple model name like 'fai-detr-m-coco' - Hub model: Format 'hub://' for models from Focoos Hub - Default directory model: Model name for models in default Focoos directory

 'fai-detr-l-obj365'
source str

Path to input image file or URL. Must be a single image file.

 required
runtime RuntimeType

Runtime backend for inference. Defaults to ONNX_CUDA32. Options include ONNX_CUDA32, ONNX_CPU, PYTORCH, etc.

 None
im_size Optional[int]

Input image size for inference. Defaults to 640. Images will be resized to this size while maintaining aspect ratio.

 640
conf Optional[float]

Confidence threshold for detections. Defaults to 0.25. Only detections above this threshold will be reported.

 0.5
save Optional[bool]

Whether to save annotated images with detection overlays. Defaults to True.

 True
output_dir Optional[str]

Directory to save all inference results.

 PREDICTIONS_DIR
save_json Optional[bool]

Whether to save detection results in JSON format. Defaults to True.

 True
save_masks Optional[bool]

Whether to save segmentation masks as separate PNG images. Defaults to True. Only applies if the model produces masks.

 True

Examples:

Basic image inference with pretrained model: 

1
focoos predict --model fai-detr-m-coco --source image.jpg

Inference with model from Focoos Hub: 

1
focoos predict --model hub://<model-ref> --source image.jpg

Inference with local model in default Focoos directory: 

1
focoos predict --model my-trained-model --source image.jpg

Image inference with custom confidence: 

1
focoos predict --model fai-detr-m-coco --source image.jpg --conf 0.5

Inference with custom output directory: 

1
focoos predict --model fai-detr-m-coco --source image.jpg                        --output-dir ./my_results --runtime ONNX_CPU

URL inference: 

1
focoos predict --model fai-detr-m-coco                        --source https://example.com/image.jpg

Only console output (no file saving): 

1
focoos predict --model fai-detr-m-coco --source image.jpg                        --save false --save-json false --save-masks false

Output

The command prints detection results to the console and optionally saves files:

Console output example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
==================================================
DETECTION RESULTS
==================================================
Found 2 detections:

  1. person
     Confidence: 0.856
     Bbox: [245, 120, 380, 450]
     Size: 135 x 330

  2. car
     Confidence: 0.742
     Bbox: [50, 200, 200, 300]
     Size: 150 x 100
==================================================

File outputs (if enabled): - {source_name}_annotated.{ext}: Annotated image with bounding boxes - {source_name}_detections.json: Structured detection data - {source_name}_masks/mask_N.png: Individual mask files (if applicable)

Note

The function currently processes single images only. For batch processing, the command needs to be run multiple times. All detection results are always printed to the console regardless of save options.

See Also
Source code in focoos/cli/cli.py 
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
@app.command("predict")
def predict(
    source: Annotated[str, typer.Option(help="Image/video path or URL (required)")],
    model: Annotated[str, typer.Option(help="Model name or path (required)")] = "fai-detr-l-obj365",
    runtime: Annotated[
        Optional[RuntimeType], typer.Option(help="Runtime type (If not provided, torch will be used)")
    ] = None,
    im_size: Annotated[Optional[int], typer.Option(help="Image size")] = 640,
    conf: Annotated[Optional[float], typer.Option(help="Confidence threshold")] = 0.5,
    output_dir: Annotated[
        Optional[str], typer.Option(help="Directory to save results (default: ~/FocoosAI/predictions/)")
    ] = PREDICTIONS_DIR,
    save: Annotated[Optional[bool], typer.Option(help="Save annotated image results")] = True,
    save_json: Annotated[Optional[bool], typer.Option(help="Save detections as JSON")] = True,
    save_masks: Annotated[Optional[bool], typer.Option(help="Save masks as separate images")] = True,
):
    """Run inference on images with flexible output options.

    This command performs inference (prediction) on input images using a trained model.
    Supports various output formats including annotated images, JSON results, and mask files.
    Results are always printed to the console.

    Supported Input:
        - **Single Images**: Local image files (loaded via `image_loader()`)
        - **URLs**: Remote image files accessible via URL

    Output Options:
        - **Console Output**: Detection results printed to terminal (always enabled)
        - **Annotated Images**: Visual results with bounding boxes and labels (if `save=True`)
        - **JSON Files**: Machine-readable detection results with coordinates and confidence (if `save_json=True`)
        - **Mask Images**: Individual mask files as PNG images (if `save_masks=True` and model produces masks)

    Args:
        model (str): Name of the model or path to model file for inference.
            Can be specified in several ways:
            - **Pretrained model**: Simple model name like 'fai-detr-m-coco'
            - **Hub model**: Format 'hub://<model-ref>' for models from Focoos Hub
            - **Default directory model**: Model name for models in default Focoos directory
        source (str): Path to input image file or URL. Must be a single image file.
        runtime (RuntimeType): Runtime backend for inference. Defaults to ONNX_CUDA32.
            Options include ONNX_CUDA32, ONNX_CPU, PYTORCH, etc.
        im_size (Optional[int]): Input image size for inference. Defaults to 640.
            Images will be resized to this size while maintaining aspect ratio.
        conf (Optional[float]): Confidence threshold for detections. Defaults to 0.25.
            Only detections above this threshold will be reported.
        save (Optional[bool]): Whether to save annotated images with detection overlays.
            Defaults to True.
        output_dir (Optional[str]): Directory to save all inference results.
        save_json (Optional[bool]): Whether to save detection results in JSON format.
            Defaults to True.
        save_masks (Optional[bool]): Whether to save segmentation masks as separate PNG images.
            Defaults to True. Only applies if the model produces masks.

    Examples:
        Basic image inference with pretrained model:
        ```bash
        focoos predict --model fai-detr-m-coco --source image.jpg
        ```

        Inference with model from Focoos Hub:
        ```bash
        focoos predict --model hub://<model-ref> --source image.jpg
        ```

        Inference with local model in default Focoos directory:
        ```bash
        focoos predict --model my-trained-model --source image.jpg
        ```

        Image inference with custom confidence:
        ```bash
        focoos predict --model fai-detr-m-coco --source image.jpg --conf 0.5
        ```

        Inference with custom output directory:
        ```bash
        focoos predict --model fai-detr-m-coco --source image.jpg \
                       --output-dir ./my_results --runtime ONNX_CPU
        ```

        URL inference:
        ```bash
        focoos predict --model fai-detr-m-coco \
                       --source https://example.com/image.jpg
        ```

        Only console output (no file saving):
        ```bash
        focoos predict --model fai-detr-m-coco --source image.jpg \
                       --save false --save-json false --save-masks false
        ```

    Output:
        The command prints detection results to the console and optionally saves files:

        Console output example:
        ```
        ==================================================
        DETECTION RESULTS
        ==================================================
        Found 2 detections:

          1. person
             Confidence: 0.856
             Bbox: [245, 120, 380, 450]
             Size: 135 x 330

          2. car
             Confidence: 0.742
             Bbox: [50, 200, 200, 300]
             Size: 150 x 100
        ==================================================
        ```

        File outputs (if enabled):
        - `{source_name}_annotated.{ext}`: Annotated image with bounding boxes
        - `{source_name}_detections.json`: Structured detection data
        - `{source_name}_masks/mask_N.png`: Individual mask files (if applicable)

    Note:
        The function currently processes single images only. For batch processing,
        the command needs to be run multiple times. All detection results are
        always printed to the console regardless of save options.

    See Also:
        - [`focoos val`][focoos.cli.cli.val]: For model validation
        - [`focoos benchmark`][focoos.cli.cli.benchmark]: For performance testing
        - [Inference Guide](../inference.md): For detailed inference documentation
    """
    typer.echo(
        f"🔮 Starting predict - Model: {model}, Source: {source}, Runtime: {runtime}, Image size: {im_size}, Conf: {conf}, Save: {save}, Output dir: {output_dir}, Save json: {save_json}, Save masks: {save_masks}"
    )
    try:
        predict_command(
            model_name=model,
            source=source,
            runtime=runtime,
            im_size=im_size,
            conf=conf,
            save=save,
            output_dir=output_dir,
            save_json=save_json,
            save_masks=save_masks,
        )
    except Exception as e:
        typer.echo(f"❌ Predict failed: {e}")

settings() #

Show current Focoos configuration settings.

This command displays the current configuration settings for Focoos, including runtime type, host URL, API key status, log level, and other configuration parameters.

Configuration includes
  • Runtime Type: Backend engine for inference
  • Host URL: API endpoint for Focoos services
  • API Key: Authentication status (masked for security)
  • Log Level: Current logging verbosity
  • Warmup Iterations: Performance optimization setting

Examples:

1
focoos settings

Output: 

1
2
3
4
5
6
Current Focoos settings:
FOCOOS_RUNTIME_TYPE=ONNX_CUDA32
FOCOOS_HOST_URL=https://api.focoos.ai
FOCOOS_API_KEY=********************
FOCOOS_LOG_LEVEL=INFO
FOCOOS_WARMUP_ITER=3

Raises:

Type Description
Exit

If there's an error accessing configuration settings.
See Also
Source code in focoos/cli/cli.py 
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
@app.command("settings")
def settings():
    """Show current Focoos configuration settings.

    This command displays the current configuration settings for Focoos,
    including runtime type, host URL, API key status, log level, and
    other configuration parameters.

    Configuration includes:
        - **Runtime Type**: Backend engine for inference
        - **Host URL**: API endpoint for Focoos services
        - **API Key**: Authentication status (masked for security)
        - **Log Level**: Current logging verbosity
        - **Warmup Iterations**: Performance optimization setting

    Examples:
        ```bash
        focoos settings
        ```

        Output:
        ```
        Current Focoos settings:
        FOCOOS_RUNTIME_TYPE=ONNX_CUDA32
        FOCOOS_HOST_URL=https://api.focoos.ai
        FOCOOS_API_KEY=********************
        FOCOOS_LOG_LEVEL=INFO
        FOCOOS_WARMUP_ITER=3
        ```

    Raises:
        typer.Exit: If there's an error accessing configuration settings.

    See Also:
        - [`focoos checks`][focoos.cli.cli.checks]: For system diagnostics
    """
    try:
        from focoos.config import FOCOOS_CONFIG

        typer.echo("Current Focoos settings:")
        typer.echo(f"FOCOOS_RUNTIME_TYPE={FOCOOS_CONFIG.runtime_type}")
        typer.echo(f"FOCOOS_HOST_URL={FOCOOS_CONFIG.default_host_url}")
        typer.echo(f"FOCOOS_API_KEY={'*' * 20 if FOCOOS_CONFIG.focoos_api_key else 'Not set'}")
        typer.echo(f"FOCOOS_LOG_LEVEL={FOCOOS_CONFIG.focoos_log_level}")
        typer.echo(f"FOCOOS_WARMUP_ITER={FOCOOS_CONFIG.warmup_iter}")
    except Exception as e:
        logger.error(f"Error showing settings: {e}")
        raise typer.Exit(1)

train(model, dataset, run_name=None, datasets_dir=None, dataset_layout=DatasetLayout.ROBOFLOW_COCO, im_size=640, output_dir=None, ckpt_dir=None, init_checkpoint=None, resume=False, num_gpus=get_gpus_count(), device='cuda', workers=4, amp_enabled=True, ddp_broadcast_buffers=False, ddp_find_unused=True, checkpointer_period=1000, checkpointer_max_to_keep=1, eval_period=50, log_period=20, samples=9, seed=42, early_stop=True, patience=10, ema_enabled=False, ema_decay=0.999, ema_warmup=2000, learning_rate=0.0005, weight_decay=0.02, max_iters=3000, batch_size=16, scheduler='MULTISTEP', optimizer='ADAMW', weight_decay_norm=0.0, weight_decay_embed=0.0, backbone_multiplier=0.1, decoder_multiplier=1.0, head_multiplier=1.0, freeze_bn=False, clip_gradients=0.1, size_divisibility=0, gather_metric_period=1, zero_grad_before_forward=False, sync_to_hub=False) #

Train a model with comprehensive configuration options.

This command initiates model training with extensive customization options for dataset handling, model architecture, optimization, and training dynamics. Supports distributed training, mixed precision, and various optimization strategies.

Training Features
  • Multi-GPU Training: Automatic distributed training support
  • Mixed Precision: Faster training with AMP (Automatic Mixed Precision)
  • Early Stopping: Prevent overfitting with validation-based stopping
  • EMA (Exponential Moving Average): Improved model stability
  • Flexible Scheduling: Multiple learning rate schedules
  • Checkpoint Management: Automatic saving and resuming

Parameters:

Name Type Description Default
model str

Name of the model architecture to train (e.g., 'fai-detr-m-coco'). Can be specified in several ways: - Pretrained model: Simple model name like 'fai-detr-m-coco' - Hub model: Format 'hub://' for models from Focoos Hub - Default directory model: Model name for models in default Focoos directory

 required
dataset str

Name of the dataset to train on (e.g., 'mydataset.zip').

 required
run_name Optional[str]

Optional name for the training run. If not provided, generates a unique name using model name and UUID.

 None
datasets_dir Optional[str]

Custom directory for datasets.

 None
dataset_layout DatasetLayout

Layout format of the dataset. Defaults to ROBOFLOW_COCO.

 ROBOFLOW_COCO
im_size int

Input image size for training. Defaults to 640.

 640
output_dir Optional[str]

Directory to save training outputs and logs.

 None
ckpt_dir Optional[str]

Directory to save model checkpoints.

 None
init_checkpoint Optional[str]

Path to initial checkpoint for transfer learning.

 None
resume bool

Whether to resume training from the latest checkpoint. Defaults to False.

 False
num_gpus int

Number of GPUs to use for training. Defaults to auto-detected count.

 get_gpus_count()
device str

Device type for training ('cuda' or 'cpu'). Defaults to 'cuda'.

 'cuda'
workers int

Number of data loading workers. Defaults to 4.

 4
amp_enabled bool

Enable Automatic Mixed Precision for faster training. Defaults to True.

 True
ddp_broadcast_buffers bool

Whether to broadcast buffers in DistributedDataParallel. Defaults to False.

 False
ddp_find_unused bool

Whether to find unused parameters in DDP. Defaults to True.

 True
checkpointer_period int

Frequency of checkpoint saving (in iterations). Defaults to 1000.

 1000
checkpointer_max_to_keep int

Maximum number of checkpoints to retain. Defaults to 1.

 1
eval_period int

Frequency of model evaluation (in iterations). Defaults to 50.

 50
log_period int

Frequency of logging metrics (in iterations). Defaults to 20.

 20
samples int

Number of sample images to log during training. Defaults to 9.

 9
seed int

Random seed for reproducible training. Defaults to 42.

 42
early_stop bool

Enable early stopping based on validation metrics. Defaults to True.

 True
patience int

Number of evaluations to wait before early stopping. Defaults to 10.

 10
ema_enabled bool

Enable Exponential Moving Average of model weights. Defaults to False.

 False
ema_decay float

Decay rate for EMA. Defaults to 0.999.

 0.999
ema_warmup int

Number of warmup steps for EMA. Defaults to 2000.

 2000
learning_rate float

Initial learning rate for optimization. Defaults to 5e-4.

 0.0005
weight_decay float

L2 regularization weight decay. Defaults to 0.02.

 0.02
max_iters int

Maximum number of training iterations. Defaults to 3000.

 3000
batch_size int

Training batch size. Defaults to 16.

 16
scheduler str

Learning rate scheduler type ('MULTISTEP', 'COSINE', etc.). Defaults to 'MULTISTEP'.

 'MULTISTEP'
optimizer str

Optimizer type ('ADAMW', 'SGD', etc.). Defaults to 'ADAMW'.

 'ADAMW'
weight_decay_norm float

Weight decay for normalization layers. Defaults to 0.0.

 0.0
weight_decay_embed float

Weight decay for embedding layers. Defaults to 0.0.

 0.0
backbone_multiplier float

Learning rate multiplier for backbone layers. Defaults to 0.1.

 0.1
decoder_multiplier float

Learning rate multiplier for decoder layers. Defaults to 1.0.

 1.0
head_multiplier float

Learning rate multiplier for head layers. Defaults to 1.0.

 1.0
freeze_bn bool

Whether to freeze batch normalization layers. Defaults to False.

 False
clip_gradients float

Gradient clipping threshold. Defaults to 0.1.

 0.1
size_divisibility int

Image size divisibility constraint. Defaults to 0.

 0
gather_metric_period int

Frequency of metric gathering (in iterations). Defaults to 1.

 1
zero_grad_before_forward bool

Whether to zero gradients before forward pass. Defaults to False.

 False
sync_to_hub bool

Whether to sync model to Focoos Hub. Defaults to False.

 False

Examples:

Basic training with pretrained model: 

1
focoos train --model fai-detr-m-coco --dataset mydataset.zip

Training with model from Focoos Hub: 

1
focoos train --model hub://<model-ref> --dataset mydataset.zip

Training with local model in default Focoos directory: 

1
focoos train --model my-saved-model --dataset mydataset.zip

Advanced training with custom parameters: 

1
focoos train --model fai-detr-m-coco --dataset mydataset.zip                      --im-size 800 --batch-size 32 --learning-rate 1e-4                      --max-iters 5000 --early-stop --patience 20

Multi-GPU training with mixed precision: 

1
focoos train --model fai-detr-m-coco --dataset custom_dataset                      --num-gpus 4 --amp-enabled --batch-size 64

Resume training from checkpoint: 

1
focoos train --model fai-detr-m-coco --dataset mydataset.zip                      --resume --ckpt-dir ./checkpoints

Raises:

Type Description
AssertionError

If device, scheduler, or optimizer parameters are invalid.
FileNotFoundError

If dataset or checkpoint files are not found.
RuntimeError

If GPU resources are insufficient or CUDA is unavailable.
See Also
Source code in focoos/cli/cli.py 
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
@app.command("train")
def train(
    model: Annotated[str, typer.Option(help="Model name (required)")],
    dataset: Annotated[str, typer.Option(help="Dataset name (required)")],
    run_name: Annotated[Optional[str], typer.Option(help="Run name")] = None,
    datasets_dir: Annotated[
        Optional[str], typer.Option(help="Datasets directory (default: ~/FocoosAI/datasets/)")
    ] = None,
    dataset_layout: Annotated[DatasetLayout, typer.Option(help="Dataset layout")] = DatasetLayout.ROBOFLOW_COCO,
    im_size: Annotated[int, typer.Option(help="Image size")] = 640,
    output_dir: Annotated[Optional[str], typer.Option(help="Output directory")] = None,
    ckpt_dir: Annotated[Optional[str], typer.Option(help="Checkpoint directory")] = None,
    init_checkpoint: Annotated[Optional[str], typer.Option(help="Initial checkpoint path")] = None,
    resume: Annotated[bool, typer.Option(help="Resume training from checkpoint")] = False,
    num_gpus: Annotated[int, typer.Option(help="Number of GPUs to use")] = get_gpus_count(),
    device: Annotated[str, typer.Option(help="Device to use")] = "cuda",
    workers: Annotated[int, typer.Option(help="Number of workers")] = 4,
    amp_enabled: Annotated[bool, typer.Option(help="Enable automatic mixed precision")] = True,
    ddp_broadcast_buffers: Annotated[bool, typer.Option(help="Broadcast buffers in DDP")] = False,
    ddp_find_unused: Annotated[bool, typer.Option(help="Find unused parameters in DDP")] = True,
    checkpointer_period: Annotated[int, typer.Option(help="Checkpoint save period")] = 1000,
    checkpointer_max_to_keep: Annotated[int, typer.Option(help="Maximum checkpoints to keep")] = 1,
    eval_period: Annotated[int, typer.Option(help="Evaluation period")] = 50,
    log_period: Annotated[int, typer.Option(help="Logging period")] = 20,
    samples: Annotated[int, typer.Option(help="Number of samples to log")] = 9,
    seed: Annotated[int, typer.Option(help="Random seed")] = 42,
    early_stop: Annotated[bool, typer.Option(help="Enable early stopping")] = True,
    patience: Annotated[int, typer.Option(help="Early stopping patience")] = 10,
    ema_enabled: Annotated[bool, typer.Option(help="Enable EMA")] = False,
    ema_decay: Annotated[float, typer.Option(help="EMA decay rate")] = 0.999,
    ema_warmup: Annotated[int, typer.Option(help="EMA warmup steps")] = 2000,
    learning_rate: Annotated[float, typer.Option(help="Learning rate")] = 5e-4,
    weight_decay: Annotated[float, typer.Option(help="Weight decay")] = 0.02,
    max_iters: Annotated[int, typer.Option(help="Maximum iterations")] = 3000,
    batch_size: Annotated[int, typer.Option(help="Batch size")] = 16,
    scheduler: Annotated[str, typer.Option(help="Learning rate scheduler")] = "MULTISTEP",
    optimizer: Annotated[str, typer.Option(help="Optimizer type")] = "ADAMW",
    weight_decay_norm: Annotated[float, typer.Option(help="Weight decay for normalization layers")] = 0.0,
    weight_decay_embed: Annotated[float, typer.Option(help="Weight decay for embedding layers")] = 0.0,
    backbone_multiplier: Annotated[float, typer.Option(help="Learning rate multiplier for backbone")] = 0.1,
    decoder_multiplier: Annotated[float, typer.Option(help="Learning rate multiplier for decoder")] = 1.0,
    head_multiplier: Annotated[float, typer.Option(help="Learning rate multiplier for head")] = 1.0,
    freeze_bn: Annotated[bool, typer.Option(help="Freeze batch normalization layers")] = False,
    clip_gradients: Annotated[float, typer.Option(help="Gradient clipping value")] = 0.1,
    size_divisibility: Annotated[int, typer.Option(help="Size divisibility")] = 0,
    gather_metric_period: Annotated[int, typer.Option(help="Metric gathering period")] = 1,
    zero_grad_before_forward: Annotated[bool, typer.Option(help="Zero gradients before forward pass")] = False,
    sync_to_hub: Annotated[bool, typer.Option(help="Sync to Focoos Hub")] = False,
):
    """Train a model with comprehensive configuration options.

    This command initiates model training with extensive customization options
    for dataset handling, model architecture, optimization, and training dynamics.
    Supports distributed training, mixed precision, and various optimization strategies.

    Training Features:
        - **Multi-GPU Training**: Automatic distributed training support
        - **Mixed Precision**: Faster training with AMP (Automatic Mixed Precision)
        - **Early Stopping**: Prevent overfitting with validation-based stopping
        - **EMA (Exponential Moving Average)**: Improved model stability
        - **Flexible Scheduling**: Multiple learning rate schedules
        - **Checkpoint Management**: Automatic saving and resuming

    Args:
        model (str): Name of the model architecture to train (e.g., 'fai-detr-m-coco').
            Can be specified in several ways:
            - **Pretrained model**: Simple model name like 'fai-detr-m-coco'
            - **Hub model**: Format 'hub://<model-ref>' for models from Focoos Hub
            - **Default directory model**: Model name for models in default Focoos directory
        dataset (str): Name of the dataset to train on (e.g., 'mydataset.zip').
        run_name (Optional[str]): Optional name for the training run. If not provided,
            generates a unique name using model name and UUID.
        datasets_dir (Optional[str]): Custom directory for datasets.
        dataset_layout (DatasetLayout): Layout format of the dataset. Defaults to ROBOFLOW_COCO.
        im_size (int): Input image size for training. Defaults to 640.
        output_dir (Optional[str]): Directory to save training outputs and logs.
        ckpt_dir (Optional[str]): Directory to save model checkpoints.
        init_checkpoint (Optional[str]): Path to initial checkpoint for transfer learning.
        resume (bool): Whether to resume training from the latest checkpoint. Defaults to False.
        num_gpus (int): Number of GPUs to use for training. Defaults to auto-detected count.
        device (str): Device type for training ('cuda' or 'cpu'). Defaults to 'cuda'.
        workers (int): Number of data loading workers. Defaults to 4.
        amp_enabled (bool): Enable Automatic Mixed Precision for faster training. Defaults to True.
        ddp_broadcast_buffers (bool): Whether to broadcast buffers in DistributedDataParallel.
            Defaults to False.
        ddp_find_unused (bool): Whether to find unused parameters in DDP. Defaults to True.
        checkpointer_period (int): Frequency of checkpoint saving (in iterations). Defaults to 1000.
        checkpointer_max_to_keep (int): Maximum number of checkpoints to retain. Defaults to 1.
        eval_period (int): Frequency of model evaluation (in iterations). Defaults to 50.
        log_period (int): Frequency of logging metrics (in iterations). Defaults to 20.
        samples (int): Number of sample images to log during training. Defaults to 9.
        seed (int): Random seed for reproducible training. Defaults to 42.
        early_stop (bool): Enable early stopping based on validation metrics. Defaults to True.
        patience (int): Number of evaluations to wait before early stopping. Defaults to 10.
        ema_enabled (bool): Enable Exponential Moving Average of model weights. Defaults to False.
        ema_decay (float): Decay rate for EMA. Defaults to 0.999.
        ema_warmup (int): Number of warmup steps for EMA. Defaults to 2000.
        learning_rate (float): Initial learning rate for optimization. Defaults to 5e-4.
        weight_decay (float): L2 regularization weight decay. Defaults to 0.02.
        max_iters (int): Maximum number of training iterations. Defaults to 3000.
        batch_size (int): Training batch size. Defaults to 16.
        scheduler (str): Learning rate scheduler type ('MULTISTEP', 'COSINE', etc.).
            Defaults to 'MULTISTEP'.
        optimizer (str): Optimizer type ('ADAMW', 'SGD', etc.). Defaults to 'ADAMW'.
        weight_decay_norm (float): Weight decay for normalization layers. Defaults to 0.0.
        weight_decay_embed (float): Weight decay for embedding layers. Defaults to 0.0.
        backbone_multiplier (float): Learning rate multiplier for backbone layers. Defaults to 0.1.
        decoder_multiplier (float): Learning rate multiplier for decoder layers. Defaults to 1.0.
        head_multiplier (float): Learning rate multiplier for head layers. Defaults to 1.0.
        freeze_bn (bool): Whether to freeze batch normalization layers. Defaults to False.
        clip_gradients (float): Gradient clipping threshold. Defaults to 0.1.
        size_divisibility (int): Image size divisibility constraint. Defaults to 0.
        gather_metric_period (int): Frequency of metric gathering (in iterations). Defaults to 1.
        zero_grad_before_forward (bool): Whether to zero gradients before forward pass.
            Defaults to False.
        sync_to_hub (bool): Whether to sync model to Focoos Hub. Defaults to False.

    Examples:
        Basic training with pretrained model:
        ```bash
        focoos train --model fai-detr-m-coco --dataset mydataset.zip
        ```

        Training with model from Focoos Hub:
        ```bash
        focoos train --model hub://<model-ref> --dataset mydataset.zip
        ```

        Training with local model in default Focoos directory:
        ```bash
        focoos train --model my-saved-model --dataset mydataset.zip
        ```

        Advanced training with custom parameters:
        ```bash
        focoos train --model fai-detr-m-coco --dataset mydataset.zip \
                     --im-size 800 --batch-size 32 --learning-rate 1e-4 \
                     --max-iters 5000 --early-stop --patience 20
        ```

        Multi-GPU training with mixed precision:
        ```bash
        focoos train --model fai-detr-m-coco --dataset custom_dataset \
                     --num-gpus 4 --amp-enabled --batch-size 64
        ```

        Resume training from checkpoint:
        ```bash
        focoos train --model fai-detr-m-coco --dataset mydataset.zip \
                     --resume --ckpt-dir ./checkpoints
        ```

    Raises:
        AssertionError: If device, scheduler, or optimizer parameters are invalid.
        FileNotFoundError: If dataset or checkpoint files are not found.
        RuntimeError: If GPU resources are insufficient or CUDA is unavailable.

    See Also:
        - [`focoos val`][focoos.cli.cli.val]: For model validation
        - [`focoos export`][focoos.cli.cli.export]: For model export
        - [Training Guide](../training.md): For detailed training documentation
    """
    typer.echo("🔍 Training arguments:")
    typer.echo(f"  Model: {model}")
    typer.echo(f"  Dataset: {dataset}")
    typer.echo(f"  Dataset layout: {dataset_layout}")
    typer.echo(f"  Image size: {im_size}")
    typer.echo(f"  Run name: {run_name}")
    typer.echo(f"  Output dir: {output_dir}")
    typer.echo(f"  Checkpoint dir: {ckpt_dir}")
    typer.echo(f"  Init checkpoint: {init_checkpoint}")
    typer.echo(f"  Resume: {resume}")
    typer.echo(f"  Num GPUs: {num_gpus}")
    typer.echo(f"  Device: {device}")
    typer.echo(f"  Workers: {workers}")
    typer.echo(f"  Batch size: {batch_size}")
    typer.echo(f"  Scheduler: {scheduler}")
    typer.echo(f"  Optimizer: {optimizer}")
    typer.echo(f"  Weight decay norm: {weight_decay_norm}")
    typer.echo(f"  Weight decay embed: {weight_decay_embed}")
    typer.echo(f"  Backbone multiplier: {backbone_multiplier}")
    typer.echo(f"  Decoder multiplier: {decoder_multiplier}")
    typer.echo(f"  Head multiplier: {head_multiplier}")

    try:
        # Cast to proper literal types
        validated_device = cast(DeviceType, device)
        assert device in get_args(DeviceType)
        validated_scheduler = cast(SchedulerType, scheduler.upper())
        assert scheduler in get_args(SchedulerType)
        validated_optimizer = cast(OptimizerType, optimizer.upper())
        assert optimizer in get_args(OptimizerType)

        train_command(
            model_name=model,
            dataset_name=dataset,
            dataset_layout=dataset_layout,
            im_size=im_size,
            run_name=run_name or f"{model}-{uuid.uuid4()}",
            output_dir=output_dir,
            ckpt_dir=ckpt_dir,
            init_checkpoint=init_checkpoint,
            resume=resume,
            num_gpus=num_gpus,
            device=validated_device,
            workers=workers,
            amp_enabled=amp_enabled,
            ddp_broadcast_buffers=ddp_broadcast_buffers,
            ddp_find_unused=ddp_find_unused,
            checkpointer_period=checkpointer_period,
            checkpointer_max_to_keep=checkpointer_max_to_keep,
            eval_period=eval_period,
            log_period=log_period,
            samples=samples,
            seed=seed,
            early_stop=early_stop,
            patience=patience,
            ema_enabled=ema_enabled,
            ema_decay=ema_decay,
            ema_warmup=ema_warmup,
            learning_rate=learning_rate,
            weight_decay=weight_decay,
            max_iters=max_iters,
            batch_size=batch_size,
            scheduler=validated_scheduler,
            optimizer=validated_optimizer,
            weight_decay_norm=weight_decay_norm,
            weight_decay_embed=weight_decay_embed,
            backbone_multiplier=backbone_multiplier,
            decoder_multiplier=decoder_multiplier,
            head_multiplier=head_multiplier,
            freeze_bn=freeze_bn,
            clip_gradients=clip_gradients,
            size_divisibility=size_divisibility,
            gather_metric_period=gather_metric_period,
            zero_grad_before_forward=zero_grad_before_forward,
            sync_to_hub=sync_to_hub,
            datasets_dir=datasets_dir,
        )
    except Exception as e:
        typer.echo(f"❌ Training failed: {e}")

val(model, dataset, datasets_dir=None, run_name=None, dataset_layout=DatasetLayout.ROBOFLOW_COCO, im_size=640, output_dir=None, ckpt_dir=None, init_checkpoint=None, resume=False, num_gpus=get_gpus_count(), device='cuda', workers=4, amp_enabled=True, ddp_broadcast_buffers=False, ddp_find_unused=True, checkpointer_period=1000, checkpointer_max_to_keep=1, eval_period=50, log_period=20, samples=9, seed=42, early_stop=True, patience=10, ema_enabled=False, ema_decay=0.999, ema_warmup=2000, learning_rate=0.0005, weight_decay=0.02, max_iters=3000, batch_size=16, scheduler='MULTISTEP', optimizer='ADAMW', weight_decay_norm=0.0, weight_decay_embed=0.0, backbone_multiplier=0.1, decoder_multiplier=1.0, head_multiplier=1.0, freeze_bn=False, clip_gradients=0.1, size_divisibility=0, gather_metric_period=1, zero_grad_before_forward=False) #

Validate a model on a dataset with comprehensive evaluation metrics.

This command performs model validation/evaluation on a specified dataset, computing various metrics such as mAP, precision, recall, and other task-specific evaluation measures. Supports the same configuration options as training for consistency in evaluation setup.

Validation Metrics
  • mAP (mean Average Precision): Overall detection accuracy
  • Precision/Recall: Per-class and overall performance
  • F1-Score: Harmonic mean of precision and recall
  • IoU (Intersection over Union): Bounding box accuracy
  • Inference Speed: FPS and latency measurements

Parameters:

Name Type Description Default
model str

Name of the model to validate (e.g., 'fai-detr-m-coco'). Can be specified in several ways: - Pretrained model: Simple model name like 'fai-detr-m-coco' - Hub model: Format 'hub://' for models from Focoos Hub - Default directory model: Model name for models in default Focoos directory

 required
dataset str

Name of the dataset for validation (e.g., 'mydataset.zip').

 required
run_name Optional[str]

Optional name for the validation run. If not provided, generates a unique name using model name and UUID.

 None
dataset_layout DatasetLayout

Layout format of the dataset. Defaults to ROBOFLOW_COCO.

 ROBOFLOW_COCO
im_size int

Input image size for validation. Defaults to 640.

 640
output_dir Optional[str]

Directory to save validation outputs and results.

 None
ckpt_dir Optional[str]

Directory containing model checkpoints.

 None
init_checkpoint Optional[str]

Path to specific checkpoint for validation.

 None
resume bool

Whether to resume from checkpoint (typically not used in validation).

 False
num_gpus int

Number of GPUs to use for validation. Defaults to auto-detected count.

 get_gpus_count()
device str

Device type for validation ('cuda' or 'cpu'). Defaults to 'cuda'.

 'cuda'
workers int

Number of data loading workers. Defaults to 4.

 4
amp_enabled bool

Enable Automatic Mixed Precision for faster inference. Defaults to True.

 True
ddp_broadcast_buffers bool

Whether to broadcast buffers in DistributedDataParallel. Defaults to False.

 False
ddp_find_unused bool

Whether to find unused parameters in DDP. Defaults to True.

 True
checkpointer_period int

Checkpoint saving frequency (not typically used in validation).

 1000
checkpointer_max_to_keep int

Maximum checkpoints to keep.

 1
eval_period int

Frequency of evaluation logging (in iterations). Defaults to 50.

 50
log_period int

Frequency of metric logging (in iterations). Defaults to 20.

 20
samples int

Number of sample images to visualize during validation. Defaults to 9.

 9
seed int

Random seed for reproducible validation. Defaults to 42.

 42
early_stop bool

Enable early stopping (not typically used in validation).

 True
patience int

Early stopping patience.

 10
ema_enabled bool

Use Exponential Moving Average weights if available.

 False
ema_decay float

EMA decay rate.

 0.999
ema_warmup int

EMA warmup steps.

 2000
learning_rate float

Learning rate (not used in validation).

 0.0005
weight_decay float

Weight decay (not used in validation).

 0.02
max_iters int

Maximum validation iterations.

 3000
batch_size int

Validation batch size. Defaults to 16.

 16
scheduler str

Scheduler type (not used in validation).

 'MULTISTEP'
optimizer str

Optimizer type (not used in validation).

 'ADAMW'
weight_decay_norm float

Weight decay for normalization layers.

 0.0
weight_decay_embed float

Weight decay for embedding layers.

 0.0
backbone_multiplier float

Backbone learning rate multiplier.

 0.1
decoder_multiplier float

Decoder learning rate multiplier.

 1.0
head_multiplier float

Head learning rate multiplier.

 1.0
freeze_bn bool

Whether to freeze batch normalization layers.

 False
clip_gradients float

Gradient clipping threshold.

 0.1
size_divisibility int

Image size divisibility constraint.

 0
gather_metric_period int

Frequency of metric gathering.

 1
zero_grad_before_forward bool

Whether to zero gradients before forward pass.

 False
datasets_dir Optional[str]

Custom directory for datasets.

 None

Examples:

Basic validation with pretrained model: 

1
focoos val --model fai-detr-m-coco --dataset mydataset.zip

Validation with model from Focoos Hub: 

1
focoos val --model hub://<model-ref> --dataset mydataset.zip

Validation with local model in default Focoos directory: 

1
focoos val --model my-checkpoint-model --dataset mydataset.zip

Validation with specific checkpoint: 

1
focoos val --model fai-detr-m-coco --dataset mydataset.zip                    --init-checkpoint path/to/checkpoint.pth --im-size 800

Multi-GPU validation: 

1
focoos val --model fai-detr-m-coco --dataset large_dataset                    --num-gpus 2 --batch-size 32

Validation with custom output directory: 

1
focoos val --model fai-detr-m-coco --dataset mydataset.zip                    --output-dir ./validation_results

Raises:

Type Description
AssertionError

If device, scheduler, or optimizer parameters are invalid.
FileNotFoundError

If dataset or checkpoint files are not found.
RuntimeError

If GPU resources are insufficient or model loading fails.
See Also
Source code in focoos/cli/cli.py 
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
@app.command("val")
def val(
    model: Annotated[str, typer.Option(help="Model name (required)")],
    dataset: Annotated[str, typer.Option(help="Dataset name (required)")],
    datasets_dir: Annotated[
        Optional[str], typer.Option(help="Datasets directory (default: ~/FocoosAI/datasets/)")
    ] = None,
    run_name: Annotated[Optional[str], typer.Option(help="Run name")] = None,
    dataset_layout: Annotated[DatasetLayout, typer.Option(help="Dataset layout")] = DatasetLayout.ROBOFLOW_COCO,
    im_size: Annotated[int, typer.Option(help="Image size")] = 640,
    output_dir: Annotated[Optional[str], typer.Option(help="Output directory")] = None,
    ckpt_dir: Annotated[Optional[str], typer.Option(help="Checkpoint directory")] = None,
    init_checkpoint: Annotated[Optional[str], typer.Option(help="Initial checkpoint")] = None,
    resume: Annotated[bool, typer.Option(help="Resume training")] = False,
    num_gpus: Annotated[int, typer.Option(help="Number of GPUs")] = get_gpus_count(),
    device: Annotated[str, typer.Option(help="Device")] = "cuda",
    workers: Annotated[int, typer.Option(help="Number of workers")] = 4,
    amp_enabled: Annotated[bool, typer.Option(help="Enable AMP")] = True,
    ddp_broadcast_buffers: Annotated[bool, typer.Option(help="DDP broadcast buffers")] = False,
    ddp_find_unused: Annotated[bool, typer.Option(help="DDP find unused")] = True,
    checkpointer_period: Annotated[int, typer.Option(help="Checkpointer period")] = 1000,
    checkpointer_max_to_keep: Annotated[int, typer.Option(help="Checkpointer max to keep")] = 1,
    eval_period: Annotated[int, typer.Option(help="Evaluation period")] = 50,
    log_period: Annotated[int, typer.Option(help="Log period")] = 20,
    samples: Annotated[int, typer.Option(help="Number of samples")] = 9,
    seed: Annotated[int, typer.Option(help="Random seed")] = 42,
    early_stop: Annotated[bool, typer.Option(help="Enable early stopping")] = True,
    patience: Annotated[int, typer.Option(help="Early stopping patience")] = 10,
    ema_enabled: Annotated[bool, typer.Option(help="Enable EMA")] = False,
    ema_decay: Annotated[float, typer.Option(help="EMA decay")] = 0.999,
    ema_warmup: Annotated[int, typer.Option(help="EMA warmup")] = 2000,
    learning_rate: Annotated[float, typer.Option(help="Learning rate")] = 5e-4,
    weight_decay: Annotated[float, typer.Option(help="Weight decay")] = 0.02,
    max_iters: Annotated[int, typer.Option(help="Maximum iterations")] = 3000,
    batch_size: Annotated[int, typer.Option(help="Batch size")] = 16,
    scheduler: Annotated[str, typer.Option(help="Scheduler type")] = "MULTISTEP",
    optimizer: Annotated[str, typer.Option(help="Optimizer type")] = "ADAMW",
    weight_decay_norm: Annotated[float, typer.Option(help="Weight decay for normalization layers")] = 0.0,
    weight_decay_embed: Annotated[float, typer.Option(help="Weight decay for embedding layers")] = 0.0,
    backbone_multiplier: Annotated[float, typer.Option(help="Backbone learning rate multiplier")] = 0.1,
    decoder_multiplier: Annotated[float, typer.Option(help="Decoder learning rate multiplier")] = 1.0,
    head_multiplier: Annotated[float, typer.Option(help="Head learning rate multiplier")] = 1.0,
    freeze_bn: Annotated[bool, typer.Option(help="Freeze batch normalization")] = False,
    clip_gradients: Annotated[float, typer.Option(help="Gradient clipping value")] = 0.1,
    size_divisibility: Annotated[int, typer.Option(help="Size divisibility")] = 0,
    gather_metric_period: Annotated[int, typer.Option(help="Gather metric period")] = 1,
    zero_grad_before_forward: Annotated[bool, typer.Option(help="Zero gradients before forward pass")] = False,
):
    """Validate a model on a dataset with comprehensive evaluation metrics.

    This command performs model validation/evaluation on a specified dataset,
    computing various metrics such as mAP, precision, recall, and other
    task-specific evaluation measures. Supports the same configuration options
    as training for consistency in evaluation setup.

    Validation Metrics:
        - **mAP (mean Average Precision)**: Overall detection accuracy
        - **Precision/Recall**: Per-class and overall performance
        - **F1-Score**: Harmonic mean of precision and recall
        - **IoU (Intersection over Union)**: Bounding box accuracy
        - **Inference Speed**: FPS and latency measurements

    Args:
        model (str): Name of the model to validate (e.g., 'fai-detr-m-coco').
            Can be specified in several ways:
            - **Pretrained model**: Simple model name like 'fai-detr-m-coco'
            - **Hub model**: Format 'hub://<model-ref>' for models from Focoos Hub
            - **Default directory model**: Model name for models in default Focoos directory
        dataset (str): Name of the dataset for validation (e.g., 'mydataset.zip').
        run_name (Optional[str]): Optional name for the validation run. If not provided,
            generates a unique name using model name and UUID.
        dataset_layout (DatasetLayout): Layout format of the dataset. Defaults to ROBOFLOW_COCO.
        im_size (int): Input image size for validation. Defaults to 640.
        output_dir (Optional[str]): Directory to save validation outputs and results.
        ckpt_dir (Optional[str]): Directory containing model checkpoints.
        init_checkpoint (Optional[str]): Path to specific checkpoint for validation.
        resume (bool): Whether to resume from checkpoint (typically not used in validation).
        num_gpus (int): Number of GPUs to use for validation. Defaults to auto-detected count.
        device (str): Device type for validation ('cuda' or 'cpu'). Defaults to 'cuda'.
        workers (int): Number of data loading workers. Defaults to 4.
        amp_enabled (bool): Enable Automatic Mixed Precision for faster inference. Defaults to True.
        ddp_broadcast_buffers (bool): Whether to broadcast buffers in DistributedDataParallel.
            Defaults to False.
        ddp_find_unused (bool): Whether to find unused parameters in DDP. Defaults to True.
        checkpointer_period (int): Checkpoint saving frequency (not typically used in validation).
        checkpointer_max_to_keep (int): Maximum checkpoints to keep.
        eval_period (int): Frequency of evaluation logging (in iterations). Defaults to 50.
        log_period (int): Frequency of metric logging (in iterations). Defaults to 20.
        samples (int): Number of sample images to visualize during validation. Defaults to 9.
        seed (int): Random seed for reproducible validation. Defaults to 42.
        early_stop (bool): Enable early stopping (not typically used in validation).
        patience (int): Early stopping patience.
        ema_enabled (bool): Use Exponential Moving Average weights if available.
        ema_decay (float): EMA decay rate.
        ema_warmup (int): EMA warmup steps.
        learning_rate (float): Learning rate (not used in validation).
        weight_decay (float): Weight decay (not used in validation).
        max_iters (int): Maximum validation iterations.
        batch_size (int): Validation batch size. Defaults to 16.
        scheduler (str): Scheduler type (not used in validation).
        optimizer (str): Optimizer type (not used in validation).
        weight_decay_norm (float): Weight decay for normalization layers.
        weight_decay_embed (float): Weight decay for embedding layers.
        backbone_multiplier (float): Backbone learning rate multiplier.
        decoder_multiplier (float): Decoder learning rate multiplier.
        head_multiplier (float): Head learning rate multiplier.
        freeze_bn (bool): Whether to freeze batch normalization layers.
        clip_gradients (float): Gradient clipping threshold.
        size_divisibility (int): Image size divisibility constraint.
        gather_metric_period (int): Frequency of metric gathering.
        zero_grad_before_forward (bool): Whether to zero gradients before forward pass.
        datasets_dir (Optional[str]): Custom directory for datasets.

    Examples:
        Basic validation with pretrained model:
        ```bash
        focoos val --model fai-detr-m-coco --dataset mydataset.zip
        ```

        Validation with model from Focoos Hub:
        ```bash
        focoos val --model hub://<model-ref> --dataset mydataset.zip
        ```

        Validation with local model in default Focoos directory:
        ```bash
        focoos val --model my-checkpoint-model --dataset mydataset.zip
        ```

        Validation with specific checkpoint:
        ```bash
        focoos val --model fai-detr-m-coco --dataset mydataset.zip \
                   --init-checkpoint path/to/checkpoint.pth --im-size 800
        ```

        Multi-GPU validation:
        ```bash
        focoos val --model fai-detr-m-coco --dataset large_dataset \
                   --num-gpus 2 --batch-size 32
        ```

        Validation with custom output directory:
        ```bash
        focoos val --model fai-detr-m-coco --dataset mydataset.zip \
                   --output-dir ./validation_results
        ```

    Raises:
        AssertionError: If device, scheduler, or optimizer parameters are invalid.
        FileNotFoundError: If dataset or checkpoint files are not found.
        RuntimeError: If GPU resources are insufficient or model loading fails.

    See Also:
        - [`focoos train`][focoos.cli.cli.train]: For model training
        - [`focoos predict`][focoos.cli.cli.predict]: For inference
        - [Validation Guide](../validation.md): For detailed validation documentation
    """

    typer.echo("🔍 Validation arguments:")
    typer.echo(f"  Model: {model}")
    typer.echo(f"  Dataset: {dataset}")
    typer.echo(f"  Dataset layout: {dataset_layout}")
    typer.echo(f"  Image size: {im_size}")
    typer.echo(f"  Run name: {run_name}")
    typer.echo(f"  Output dir: {output_dir}")
    typer.echo(f"  Checkpoint dir: {ckpt_dir}")
    typer.echo(f"  Init checkpoint: {init_checkpoint}")
    typer.echo(f"  Resume: {resume}")
    typer.echo(f"  Num GPUs: {num_gpus}")
    typer.echo(f"  Device: {device}")
    typer.echo(f"  Workers: {workers}")
    typer.echo(f"  Batch size: {batch_size}")
    typer.echo(f"  Learning rate: {learning_rate}")
    typer.echo(f"  Weight decay: {weight_decay}")
    typer.echo(f"  Max iterations: {max_iters}")
    typer.echo(f"  Scheduler: {scheduler}")
    typer.echo(f"  Optimizer: {optimizer}")
    typer.echo(f"  Weight decay norm: {weight_decay_norm}")
    typer.echo(f"  Weight decay embed: {weight_decay_embed}")
    typer.echo(f"  Backbone multiplier: {backbone_multiplier}")
    typer.echo(f"  Decoder multiplier: {decoder_multiplier}")
    typer.echo(f"  Head multiplier: {head_multiplier}")
    typer.echo(f"  Freeze BN: {freeze_bn}")

    try:
        validated_device = cast(DeviceType, device)
        assert device in get_args(DeviceType)
        validated_scheduler = cast(SchedulerType, scheduler.upper())
        assert scheduler in get_args(SchedulerType)
        validated_optimizer = cast(OptimizerType, optimizer.upper())
        assert optimizer in get_args(OptimizerType)

        val_command(
            model_name=model,
            dataset_name=dataset,
            dataset_layout=dataset_layout,
            im_size=im_size,
            run_name=run_name or f"{model}-{uuid.uuid4()}",
            output_dir=output_dir,
            ckpt_dir=ckpt_dir,
            init_checkpoint=init_checkpoint,
            resume=resume,
            num_gpus=num_gpus,
            device=validated_device,
            workers=workers,
            amp_enabled=amp_enabled,
            ddp_broadcast_buffers=ddp_broadcast_buffers,
            ddp_find_unused=ddp_find_unused,
            checkpointer_period=checkpointer_period,
            checkpointer_max_to_keep=checkpointer_max_to_keep,
            eval_period=eval_period,
            log_period=log_period,
            samples=samples,
            seed=seed,
            early_stop=early_stop,
            patience=patience,
            ema_enabled=ema_enabled,
            ema_decay=ema_decay,
            ema_warmup=ema_warmup,
            learning_rate=learning_rate,
            weight_decay=weight_decay,
            max_iters=max_iters,
            batch_size=batch_size,
            scheduler=validated_scheduler,
            optimizer=validated_optimizer,
            weight_decay_norm=weight_decay_norm,
            weight_decay_embed=weight_decay_embed,
            backbone_multiplier=backbone_multiplier,
            decoder_multiplier=decoder_multiplier,
            head_multiplier=head_multiplier,
            freeze_bn=freeze_bn,
            clip_gradients=clip_gradients,
            size_divisibility=size_divisibility,
            gather_metric_period=gather_metric_period,
            zero_grad_before_forward=zero_grad_before_forward,
            datasets_dir=datasets_dir,
        )
    except Exception as e:
        typer.echo(f"❌ Validation failed: {e}")

version() #

Show Focoos version information.

This command displays the current version of the Focoos library installed on the system. If the version cannot be determined, it shows "Unknown".

Examples:

1
focoos version

Output: 

1
Focoos version: 0.15.0

Raises:

Type Description
Exit

If there's an error retrieving version information.
See Also
Source code in focoos/cli/cli.py 
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
@app.command("version")
def version():
    """Show Focoos version information.

    This command displays the current version of the Focoos library installed
    on the system. If the version cannot be determined, it shows "Unknown".

    Examples:
        ```bash
        focoos version
        ```

        Output:
        ```
        Focoos version: 0.15.0
        ```

    Raises:
        typer.Exit: If there's an error retrieving version information.

    See Also:
        - [`focoos checks`][focoos.cli.cli.checks]: For system diagnostics
        - [`focoos settings`][focoos.cli.cli.settings]: For configuration info
    """
    try:
        from focoos.utils.system import get_focoos_version

        version = get_focoos_version()
        typer.echo(f"Focoos version: {version}")
    except Exception:
        typer.echo("Focoos version: Unknown")

Hub command implementation.

This module implements the hub-related commands for the Focoos CLI. It provides functionality to interact with the Focoos Hub, including listing available models and datasets, both private and shared resources.

The Hub commands allow users to: - Browse and discover available pretrained models - List private and shared datasets - Get detailed information about model specifications - Access dataset metadata and statistics

Examples:

List available models: 

1
focoos hub models

List datasets including shared ones: 

1
focoos hub datasets --include-shared

Download a dataset: 

1
focoos hub dataset download --ref my-dataset --path ./data

Upload a dataset: 

1
focoos hub dataset upload --ref my-dataset --path ./data.zip

See Also

datasets(include_shared=typer.Option(False, help='Include shared/public datasets in addition to private ones')) #

List available datasets from the Focoos Hub.

Retrieves and displays datasets available on the Focoos Hub. By default, only shows private datasets associated with your account. Use the --include-shared flag to also include publicly shared datasets.

For each dataset, displays comprehensive information including: - Name: Human-readable dataset name - Reference: Unique dataset identifier for CLI usage - Task: Computer vision task type - Layout: Dataset format/structure - Description: Dataset description and details - Statistics: Training/validation split sizes and total size

Parameters:

Name Type Description Default
include_shared bool

Whether to include shared/public datasets in addition to private ones. Defaults to False.

 Option(False, help='Include shared/public datasets in addition to private ones')

Examples:

1
2
3
4
5
# List only your private datasets
focoos hub datasets

# List both private and shared datasets
focoos hub datasets --include-shared

Output example: 

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
🔍 Found 3 dataset(s):

📦 Dataset #1
   🏷️  Name: My Custom Dataset
   🔗 Reference: my-custom-dataset
   🎯 Task: object_detection
   📋 Layout: roboflow_coco
   📝 Description: Custom dataset for object detection
   🤖 Train Length: 1000
   🤖 Val Length: 200
   🤖 Size MB: 150.5

Note
  • This command requires an internet connection to access the Focoos Hub.
  • This command requires a Focoos API Key to be set in the environment variable FOCOOS_API_KEY.
  • Shared datasets may require appropriate permissions to access.
Source code in focoos/cli/commands/hub.py 
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
@app.command()
def datasets(
    include_shared: bool = typer.Option(False, help="Include shared/public datasets in addition to private ones"),
):
    """List available datasets from the Focoos Hub.

    Retrieves and displays datasets available on the Focoos Hub. By default,
    only shows private datasets associated with your account. Use the
    `--include-shared` flag to also include publicly shared datasets.

    For each dataset, displays comprehensive information including:
    - **Name**: Human-readable dataset name
    - **Reference**: Unique dataset identifier for CLI usage
    - **Task**: Computer vision task type
    - **Layout**: Dataset format/structure
    - **Description**: Dataset description and details
    - **Statistics**: Training/validation split sizes and total size

    Args:
        include_shared (bool, optional): Whether to include shared/public datasets
            in addition to private ones. Defaults to False.

    Examples:
        ```bash
        # List only your private datasets
        focoos hub datasets

        # List both private and shared datasets
        focoos hub datasets --include-shared
        ```

        Output example:
        ```
        🔍 Found 3 dataset(s):

        📦 Dataset #1
           🏷️  Name: My Custom Dataset
           🔗 Reference: my-custom-dataset
           🎯 Task: object_detection
           📋 Layout: roboflow_coco
           📝 Description: Custom dataset for object detection
           🤖 Train Length: 1000
           🤖 Val Length: 200
           🤖 Size MB: 150.5
        ```

    Note:
        - This command requires an internet connection to access the Focoos Hub.
        - This command requires a Focoos API Key to be set in the environment variable `FOCOOS_API_KEY`.
        - Shared datasets may require appropriate permissions to access.
    """
    typer.echo("Listing datasets...")
    try:
        focoos_hub = FocoosHUB()
        datasets = focoos_hub.list_remote_datasets(include_shared=include_shared)
        if not datasets:
            dataset_type = "shared and private" if include_shared else "private"
            typer.echo(f"❌ No {dataset_type} datasets found.")
            return

        dataset_type_desc = "shared and private" if include_shared else "private"
        typer.echo(f"🔍 Found {len(datasets)} {dataset_type_desc} dataset(s):\n")

        for i, dataset in enumerate(datasets, 1):
            typer.echo(f"📦 Dataset #{i}")
            typer.echo(f"   🏷️  Name: {dataset.name}")
            typer.echo(f"   🔗 Reference: {dataset.ref}")
            typer.echo(f"   🎯 Task: {dataset.task}")
            typer.echo(f"   📋 Layout: {dataset.layout}")
            typer.echo(f"   📝 Description: {dataset.description}")
            if dataset.spec:
                typer.echo(f"   📊 Train Length: {dataset.spec.train_length}")
                typer.echo(f"   📊 Val Length: {dataset.spec.valid_length}")
                typer.echo(f"   📊 Size MB: {dataset.spec.size_mb}")

            if i < len(datasets):
                typer.echo("   " + "─" * 50)
                typer.echo("")
    except Exception as e:
        typer.echo(f"❌ Failed to list datasets: {e}")
        raise typer.Exit(1)

download(ref, path=None) #

Download a dataset from the Focoos Hub.

Downloads a dataset from the Focoos Hub to a specified local path.

Parameters:

Name Type Description Default
ref str

The reference ID of the dataset to download

 required
path str

Path to download the dataset to

 None

Examples:

1
2
# Download a dataset to a specific path
focoos hub dataset download --ref my-dataset-ref --path ./data
Notes
  • This command requires an internet connection to access the Focoos Hub.
  • This command requires a Focoos API Key to be set in the environment variable FOCOOS_API_KEY.
Source code in focoos/cli/commands/hub.py 
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
@dataset_app.command()
def download(
    ref: Annotated[str, typer.Option(..., help="The reference ID of the dataset to download")],
    path: Annotated[Optional[str], typer.Option(help="Path to download the dataset to")] = None,
):
    """Download a dataset from the Focoos Hub.

    Downloads a dataset from the Focoos Hub to a specified local path.

    Args:
        ref (str): The reference ID of the dataset to download
        path (str): Path to download the dataset to

    Examples:
        ```bash
        # Download a dataset to a specific path
        focoos hub dataset download --ref my-dataset-ref --path ./data
        ```

    Notes:
        - This command requires an internet connection to access the Focoos Hub.
        - This command requires a Focoos API Key to be set in the environment variable `FOCOOS_API_KEY`.
    """
    typer.echo(f"Downloading dataset from {ref} to {path}...")
    try:
        focoos_hub = FocoosHUB()
        dataset = focoos_hub.get_remote_dataset(ref)
        if path:
            dataset.download_data(path)
        else:
            dataset.download_data()
    except Exception as e:
        typer.echo(f"❌ Failed to download dataset: {e}")
        raise typer.Exit(1)

main() #

Hub commands for interacting with the Focoos Hub.

The Focoos Hub provides access to pretrained models and datasets. Use subcommands to list and discover available resources.

Available subcommands: - models: List the available user models - datasets: List the available user datasets (private and optionally shared) - dataset: Dataset operations (download, upload)

Notes
  • This command requires an internet connection to access the Focoos Hub.
  • This command requires a Focoos API Key to be set in the environment variable FOCOOS_API_KEY.

Examples:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
# List all available models
focoos hub models

# List your datasets
focoos hub datasets

# List datasets including shared ones
focoos hub datasets --include-shared

# Download a dataset
focoos hub dataset download --ref my-dataset --path ./data

# Upload a dataset
focoos hub dataset upload --ref my-dataset --path ./data.zip
Source code in focoos/cli/commands/hub.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
@app.callback()
def main():
    """Hub commands for interacting with the Focoos Hub.

    The Focoos Hub provides access to pretrained models and datasets.
    Use subcommands to list and discover available resources.

    Available subcommands:
    - `models`: List the available user models
    - `datasets`: List the available user datasets (private and optionally shared)
    - `dataset`: Dataset operations (download, upload)

    Notes:
        - This command requires an internet connection to access the Focoos Hub.
        - This command requires a Focoos API Key to be set in the environment variable `FOCOOS_API_KEY`.

    Examples:

        # List all available models
        focoos hub models

        # List your datasets
        focoos hub datasets

        # List datasets including shared ones
        focoos hub datasets --include-shared

        # Download a dataset
        focoos hub dataset download --ref my-dataset --path ./data

        # Upload a dataset
        focoos hub dataset upload --ref my-dataset --path ./data.zip
    """
    pass

models() #

List all available pretrained models from the Focoos Hub.

Retrieves and displays a comprehensive list of all pretrained models available on the Focoos Hub. For each model, shows detailed information including name, reference, task type, description, status, and model type.

The displayed information includes: - Name: Human-readable model name - Reference: Unique model identifier for CLI usage - Task: Computer vision task (detection, segmentation, classification) - Description: Detailed model description and capabilities - Status: Model availability status - Focoos Model: Model architecture/family information

Examples:

1
2
# List all available models
focoos hub models

Output example: 

1
2
3
4
5
6
7
8
9
🔍 Found 12 model(s):

📦 Model #1
   🏷️  Name: FAI DETR Medium COCO
   🔗 Reference: fai-detr-m-coco
   🎯 Task: object_detection
   📝 Description: Medium-sized DETR model trained on COCO dataset
   ⚡ Status: ready
   🤖 Focoos Model: fai_detr

Note
  • This command requires an internet connection to access the Focoos Hub.
  • This command requires a Focoos API Key to be set in the environment variable FOCOOS_API_KEY.
Source code in focoos/cli/commands/hub.py 
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
@app.command()
def models():
    """List all available pretrained models from the Focoos Hub.

    Retrieves and displays a comprehensive list of all pretrained models
    available on the Focoos Hub. For each model, shows detailed information
    including name, reference, task type, description, status, and model type.

    The displayed information includes:
    - **Name**: Human-readable model name
    - **Reference**: Unique model identifier for CLI usage
    - **Task**: Computer vision task (detection, segmentation, classification)
    - **Description**: Detailed model description and capabilities
    - **Status**: Model availability status
    - **Focoos Model**: Model architecture/family information

    Examples:
        ```bash
        # List all available models
        focoos hub models
        ```

        Output example:
        ```
        🔍 Found 12 model(s):

        📦 Model #1
           🏷️  Name: FAI DETR Medium COCO
           🔗 Reference: fai-detr-m-coco
           🎯 Task: object_detection
           📝 Description: Medium-sized DETR model trained on COCO dataset
           ⚡ Status: ready
           🤖 Focoos Model: fai_detr
        ```

    Note:
        - This command requires an internet connection to access the Focoos Hub.
        - This command requires a Focoos API Key to be set in the environment variable `FOCOOS_API_KEY`.
    """
    typer.echo("Listing models...")
    try:
        focoos_hub = FocoosHUB()
        models = focoos_hub.list_remote_models()
        if not models:
            typer.echo("❌ No models found.")
            return

        typer.echo(f"🔍 Found {len(models)} model(s):\n")

        for i, model in enumerate(models, 1):
            typer.echo(f"📦 Model #{i}")
            typer.echo(f"   🏷️  Name: {model.name}")
            typer.echo(f"   🔗 Reference: {model.ref}")
            typer.echo(f"   🎯 Task: {model.task}")
            typer.echo(f"   📝 Description: {model.description}")
            typer.echo(f"   ⚡ Status: {model.status}")
            typer.echo(f"   🤖 Focoos Model: {model.focoos_model}")

            if i < len(models):
                typer.echo("   " + "─" * 50)
                typer.echo("")
    except Exception as e:
        typer.echo(f"❌ Failed to list models: {e}")
        raise typer.Exit(1)

upload(ref, path) #

Upload a dataset to the Focoos Hub (You must first create a dataset on the Focoos hub).

Uploads a dataset to the Focoos Hub from a specified local path.

Parameters:

Name Type Description Default
ref str

The reference ID of the dataset to upload

 required
path str

Path to upload the dataset from

 required

Examples:

1
2
# Upload a dataset from a specific path
focoos hub dataset upload --ref my-dataset-ref --path ./data.zip

For more information on how the dataset should be structured look at the documentation.

Notes
  • This command requires an internet connection to access the Focoos Hub.
  • This command requires a Focoos API Key to be set in the environment variable FOCOOS_API_KEY.
  • You must first create a dataset on the Focoos hub.
Source code in focoos/cli/commands/hub.py 
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
@dataset_app.command()
def upload(
    ref: Annotated[str, typer.Option(..., help="The reference ID of the dataset to upload")],
    path: Annotated[str, typer.Option(..., help="Path to upload the dataset from")],
):
    """Upload a dataset to the Focoos Hub (You must first create a dataset on the Focoos hub).

    Uploads a dataset to the Focoos Hub from a specified local path.

    Args:
        ref (str): The reference ID of the dataset to upload
        path (str): Path to upload the dataset from

    Examples:
        ```bash
        # Upload a dataset from a specific path
        focoos hub dataset upload --ref my-dataset-ref --path ./data.zip
        ```

    For more information on how the dataset should be structured look at the [`documentation`](../api/ports.md#focoos.ports.DatasetLayout).

    Notes:
        - This command requires an internet connection to access the Focoos Hub.
        - This command requires a Focoos API Key to be set in the environment variable `FOCOOS_API_KEY`.
        - You must first create a dataset on the Focoos hub.
    """
    typer.echo(f"Uploading dataset from {path} to {ref}...")

    try:
        focoos_hub = FocoosHUB()
        dataset = focoos_hub.get_remote_dataset(ref)
        spec = dataset.upload_data(path)
        dataset_info = dataset.get_info()
        if not spec:
            raise Exception("Failed to upload dataset.")
        typer.echo("✅ Dataset uploaded successfully!")
        typer.echo(f"   🏷️  Name: {dataset_info.name}")
        typer.echo(f"   🔗 Reference: {dataset_info.ref}")
        typer.echo(f"   🎯 Task: {dataset_info.task}")
        typer.echo(f"   📋 Layout: {dataset_info.layout}")
        typer.echo(f"   📝 Description: {dataset_info.description}")
        typer.echo(f"   📊 Train Length: {spec.train_length}")
        typer.echo(f"   📊 Val Length: {spec.valid_length}")
        typer.echo(f"   📊 Size MB: {spec.size_mb}")
    except Exception as e:
        typer.echo(f"❌ Failed to upload dataset: {e}")
        raise typer.Exit(1)