Metadata-Version: 2.4
Name: usd_search_client
Version: 1.2.0
Summary: USD Search and Asset Graph Search APIs
License: MIT
License-File: LICENSE.md
Keywords: OpenAPI,USD Search,Asset Graph Search,OpenUSD,Omniverse
Author: NVIDIA
Requires-Python: >=3.8,<4.0
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.8
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Requires-Dist: aiohttp (>=3.8.4)
Requires-Dist: aiohttp-retry (>=2.8.3)
Requires-Dist: pydantic (>=2)
Requires-Dist: python-dateutil (>=2.8.2)
Requires-Dist: typing-extensions (>=4.7.1)
Requires-Dist: urllib3 (>=1.25.3)
Project-URL: Repository, https://github.com/NVIDIA-Omniverse/usdsearch-client
Description-Content-Type: text/markdown

# usd-search-client
# USD Search API Overview
**USD Search API** is a collection of cloud-native microservices that enable developers, creators, and workflow specialists to efficiently search through vast collections of OpenUSD data, images, and other assets using natural language or image-based inputs.
With these production-ready microservices, developers can deploy USD Search API onto their own infrastructure. With USD Search API’s artificial intelligence (AI) features, you can quickly locate untagged and unstructured 3D data and digital assets, saving time navigating unstructured, untagged 3D data. USD Search API is capable of searching and indexing 3D asset databases, as well as navigating complex 3D scenes to perform spatial searches, without requiring manual tagging of assets.
## Features
- **Natural Language Searches:** - Utilize AI to search for images and USD-based 3D models using simple, descriptive language.
- **Image Similarity Searches:** - Find images similar to a reference image through AI-driven image comparisons.
- **Metadata Filtering:** - Filter search results by file name, file type, creation/modification dates, file size, and creator/modifier metadata.
- **USD Content Filtering with Asset Graph Search:** - When used with the Asset Graph Search, search capabilities are expanded to include filtering based on USD properties and object dimensions.
- **Multiple Storage Backend Support:** - Compatible with various storage backends, including AWS S3 buckets and Omniverse Nucleus server.
- **Advanced File Name, Extension, and Path Filters:** - Use wildcards for broad or specific file name and extension searches.
- **Date and Size Range Filtering:** - Specify assets created or modified within certain date ranges or file sizes larger or smaller than a designated threshold.
- **User-based Filtering:** - Filter assets based on their creator or modifier, allowing for searches tailored to particular users' contributions.
- **Embedding-based Similarity Threshold:** - Set a similarity threshold for more nuanced control over search results in embedding-based searches.
- **Custom Search Paths and Scenes:** - Specify search locations within the storage backend or conduct searches within specific scenes for targeted results.
- **Return Detailed Results:** - Option to include images, metadata, root prims, and predictions in the search results.

# Asset Graph Search (AGS) API Overview
**Asset Graph Search (AGS)** provides advanced querying capabilities for assets and USD trees indexed in a graph database. It supports proximity queries based on coordinates or prims to find objects within specified areas or radii, sorted by distance, and includes transformation options for vector alignment. The API also offers dependency and reverse dependency searches, helping to identify all assets referenced in a scene or scenes containing a particular asset, which can optimize scene loading and track dependency changes. By combining different query types, the AGS API enables complex scenarios for scene understanding, manipulation, and generation. Integrated with USD Search it provides in-scene search functionality.
## Features
- **Proximity Queries:** - Find objects within a specified bounding box or radius. - Results sorted by distance with options for vector alignment using a transformation matrix.
- **USD Property Queries:** - Enables querying objects in a 3D scene using USD properties, such as finding all assets with a specific semantic label.
- **Asset Dependency Searches:** - Identify all assets referenced in a scene — including USD references, material references, or textures. - Reverse search to find all scenes containing a particular asset.
- **Combined Query Capabilities:** - Enable complex scenarios for enhanced scene understanding, manipulation, and generation.
- **Integration with USD Search:** - Provides in-scene search functionality.


This Python package is automatically generated by the [OpenAPI Generator](https://openapi-generator.tech) project:

- API version: 1.2.0
- Package version: 1.0.0
- Generator version: 7.8.0
- Build package: org.openapitools.codegen.languages.PythonClientCodegen

## Requirements.

Python 3.8+

## Installation & Usage
### pip install

You can install the package directly using:

```sh
pip install usd-search-client --extra-index-url https://pypi.nvidia.com
```

Then import the package:
```python
import usd_search_client
```

## Getting Started

Please follow the [installation procedure](#installation--usage) and then run on of the following examples:

### Basic search API example

```python
import asyncio

import usd_search_client
from usd_search_client.rest import ApiException
from pprint import pprint

# See configuration.py for a list of all supported configuration parameters.
configuration = usd_search_client.Configuration(
    host = "http://api.my-usd-search-instance.example.com"
)


# The client may configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: APIKeyHeader

# configuration.api_key['APIKeyHeader'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['APIKeyHeader'] = 'Bearer'

# Configure HTTP basic authorization: HTTPBasic
# configuration = usd_search_client.Configuration(
#     username = os.environ["USERNAME"],
#     password = os.environ["PASSWORD"]
# )

# Configure Bearer authorization: HTTPBearer
# configuration = usd_search_client.Configuration(
#     access_token = os.environ["BEARER_TOKEN"]
# )

async def call_search_api(api_client_config):
    # Enter a context with an instance of the API client
    async with usd_search_client.ApiClient(api_client_config) as api_client:
        # Create an instance of the API class
        search_request = usd_search_client.BasicSearchRequest(description="box")

        try:
            # Search Post
            api_response = await usd_search_client.search(search_request, api_client=api_client)
            print("The response of basic search method:\n")
            pprint(api_response)
        except Exception as e:
            print("Exception when calling basic search method: %s\n" % e)

asyncio.run(call_search_api(configuration))
```

### Hybrid search API example

```python
import asyncio

import usd_search_client
from usd_search_client.rest import ApiException
from usd_search_client import BasicSearchRequest
from usd_search_client.models.vector_query import VectorQuery, VectorQueryType
from usd_search_client.models.query import Query
from pprint import pprint

# See configuration.py for a list of all supported configuration parameters.
configuration = usd_search_client.Configuration(
    host = "http://api.my-usd-search-instance.example.com"
)


# The client may configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: APIKeyHeader

# configuration.api_key['APIKeyHeader'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['APIKeyHeader'] = 'Bearer'

# Configure HTTP basic authorization: HTTPBasic
# configuration = usd_search_client.Configuration(
#     username = os.environ["USERNAME"],
#     password = os.environ["PASSWORD"]
# )

# Configure Bearer authorization: HTTPBearer
# configuration = usd_search_client.Configuration(
#     access_token = os.environ["BEARER_TOKEN"]
# )

async def call_search_api(api_client_config):
    # Enter a context with an instance of the API client
    async with usd_search_client.ApiClient(api_client_config) as api_client:
        # Create an instance of the API class
        request = BasicSearchRequest(
            hybrid_text_query="red car",
            vector_queries=[
                VectorQuery(
                    field_name="clip-embedding.embedding",
                    query_type=VectorQueryType.TEXT,
                    query=Query(actual_instance="red car")
                )
            ],
            return_metadata=True,
            return_images=True,
            limit=10
        )

        try:
            # Search Post
            api_response = await usd_search_client.search_hybrid(request, api_client=api_client)
            print("The response of Hybrid Search method:\n")
            pprint(api_response)
        except Exception as e:
            print("Exception when calling Hybrid Search method: %s\n" % e)

asyncio.run(call_search_api(configuration))
```

### Images API example

```python
import asyncio

import usd_search_client
from usd_search_client.rest import ApiException
from usd_search_client import BasicSearchRequest
from PIL import Image
import io

# See configuration.py for a list of all supported configuration parameters.
configuration = usd_search_client.Configuration(
    host = "http://api.my-usd-search-instance.example.com"
)


# The client may configure the authentication and authorization parameters
# in accordance with the API server security policy.
# Examples for each auth method are provided below, use the example that
# satisfies your auth use case.

# Configure API key authorization: APIKeyHeader

# configuration.api_key['APIKeyHeader'] = os.environ["API_KEY"]

# Uncomment below to setup prefix (e.g. Bearer) for API key, if needed
# configuration.api_key_prefix['APIKeyHeader'] = 'Bearer'

# Configure HTTP basic authorization: HTTPBasic
# configuration = usd_search_client.Configuration(
#     username = os.environ["USERNAME"],
#     password = os.environ["PASSWORD"]
# )

# Configure Bearer authorization: HTTPBearer
# configuration = usd_search_client.Configuration(
#     access_token = os.environ["BEARER_TOKEN"]
# )

async def call_search_and_images_api(api_client_config):
    # Enter a context with an instance of the API client
    async with usd_search_client.ApiClient(api_client_config) as api_client:
        # Create an instance of the API class
        search_request = BasicSearchRequest(file_extension_include="usd")
        try:
            response = await usd_search_client.search(search_request, api_client=api_client)
            url = response[0].url
            image_response = await usd_search_client.get_images(asset_url=url, api_client=api_client)
            im = Image.open(io.BytesIO(image_response))
            im.show()
        except Exception as e:
            print("Exception when calling Hybrid Search method: %s\n" % e)

asyncio.run(call_search_and_images_api(configuration))
```

## Documentation for API Endpoints

All URIs are relative to *http://api.my-usd-search-instance.example.com*

Class | Method | HTTP request | Description
------------ | ------------- | ------------- | -------------
*AGSAssetGraphApi* | [**get_dependencies_flat_dependency_graph_flat_get**](docs/AGSAssetGraphApi.md#get_dependencies_flat_dependency_graph_flat_get) | **GET** /dependency_graph/flat | Get Dependencies Flat
*AGSAssetGraphApi* | [**get_dependencies_graph_dependency_graph_graph_get**](docs/AGSAssetGraphApi.md#get_dependencies_graph_dependency_graph_graph_get) | **GET** /dependency_graph/graph | Get Dependencies Graph
*AGSAssetGraphApi* | [**get_dependencies_inverse_dependency_graph_inverse_flat_get**](docs/AGSAssetGraphApi.md#get_dependencies_inverse_dependency_graph_inverse_flat_get) | **GET** /dependency_graph/inverse/flat | Get Dependencies Inverse
*AGSAssetGraphApi* | [**get_inverse_dependencies_graph_dependency_graph_inverse_graph_get**](docs/AGSAssetGraphApi.md#get_inverse_dependencies_graph_dependency_graph_inverse_graph_get) | **GET** /dependency_graph/inverse/graph | Get Inverse Dependencies Graph
*AGSSceneGraphApi* | [**get_prims_asset_graph_usd_prims_get**](docs/AGSSceneGraphApi.md#get_prims_asset_graph_usd_prims_get) | **GET** /asset_graph/usd/prims | Get Prims
*AGSSceneGraphApi* | [**scene_summary_asset_graph_usd_scene_summary_get**](docs/AGSSceneGraphApi.md#scene_summary_asset_graph_usd_scene_summary_get) | **GET** /asset_graph/usd/scene_summary/ | Scene Summary
*AGSSpatialGraphApi* | [**get_prims_within_bounding_box_asset_graph_usd_prims_spatial_bbox_get**](docs/AGSSpatialGraphApi.md#get_prims_within_bounding_box_asset_graph_usd_prims_spatial_bbox_get) | **GET** /asset_graph/usd/prims/spatial_bbox | Get Prims Within Bounding Box
*AGSSpatialGraphApi* | [**get_prims_within_radius_asset_graph_usd_prims_spatial_get**](docs/AGSSpatialGraphApi.md#get_prims_within_radius_asset_graph_usd_prims_spatial_get) | **GET** /asset_graph/usd/prims/spatial | Get Prims Within Radius
*AISearchApi* | [**search_post_v2_deepsearch_search_post**](docs/AISearchApi.md#search_post_v2_deepsearch_search_post) | **POST** /search | Search Post
*AISearchApi* | [**search_post_v3_deepsearch_search_post**](docs/AISearchApi.md#search_post_v3_deepsearch_search_post) | **POST** /search_hybrid | Search Post
*AISearchApi* | [**search_v2_deepsearch_search_get**](docs/AISearchApi.md#search_v2_deepsearch_search_get) | **GET** /search | Search
*AISearchApi* | [**stats_usd_properties_v2_deepsearch_search_stats_usd_properties_get**](docs/AISearchApi.md#stats_usd_properties_v2_deepsearch_search_stats_usd_properties_get) | **GET** /search/stats/usd_properties | Stats Usd Properties
*AssetApi* | [**get_asset_status_info_indexing_asset_status_get**](docs/AssetApi.md#get_asset_status_info_indexing_asset_status_get) | **GET** /info/indexing/asset/status | Get Asset Status
*AssetApi* | [**submit_for_processing_process_asset_get**](docs/AssetApi.md#submit_for_processing_process_asset_get) | **GET** /process/asset | On-demand asset processing
*ImagesApi* | [**get_image_v3_images_get**](docs/ImagesApi.md#get_image_v3_images_get) | **GET** /images | Get Image
*PluginsApi* | [**list_plugins_info_plugins_get**](docs/PluginsApi.md#list_plugins_info_plugins_get) | **GET** /info/plugins | List of supported plugins
*StorageBackendApi* | [**get_storage_backend_info_info_backend_storage_get**](docs/StorageBackendApi.md#get_storage_backend_info_info_backend_storage_get) | **GET** /info/backend/storage | Get Storage Backend Info
*DefaultApi* | [**metrics_metrics_get**](docs/DefaultApi.md#metrics_metrics_get) | **GET** /metrics | Metrics

## Documentation For Models

 - [AGSAssetData](docs/AGSAssetData.md)
 - [AXIS](docs/AXIS.md)
 - [Asset](docs/Asset.md)
 - [AssetGraph](docs/AssetGraph.md)
 - [AssetRelationship](docs/AssetRelationship.md)
 - [AssetStorageBackendInfo](docs/AssetStorageBackendInfo.md)
 - [AvailableStorageClients](docs/AvailableStorageClients.md)
 - [BackendStatusType](docs/BackendStatusType.md)
 - [CreatedDateSeconds](docs/CreatedDateSeconds.md)
 - [DeepSearchSearchRequestV2](docs/DeepSearchSearchRequestV2.md)
 - [DeepsearchApiRoutersV2ModelsSearchResult](docs/DeepsearchApiRoutersV2ModelsSearchResult.md)
 - [DeepsearchApiSearchBackendModelsSearchResult](docs/DeepsearchApiSearchBackendModelsSearchResult.md)
 - [DeletedDateSeconds](docs/DeletedDateSeconds.md)
 - [EdgeType](docs/EdgeType.md)
 - [Empty](docs/Empty.md)
 - [Event](docs/Event.md)
 - [EventMapping](docs/EventMapping.md)
 - [FieldScoreConfig](docs/FieldScoreConfig.md)
 - [HTTPValidationError](docs/HTTPValidationError.md)
 - [HashType](docs/HashType.md)
 - [HashValue](docs/HashValue.md)
 - [HybridTextConfig](docs/HybridTextConfig.md)
 - [JobItemType](docs/JobItemType.md)
 - [KeyValuePair](docs/KeyValuePair.md)
 - [LocationInner](docs/LocationInner.md)
 - [Metadata](docs/Metadata.md)
 - [ModifiedDateSeconds](docs/ModifiedDateSeconds.md)
 - [Mounted](docs/Mounted.md)
 - [PathType](docs/PathType.md)
 - [PluginDescription](docs/PluginDescription.md)
 - [PluginInfo](docs/PluginInfo.md)
 - [PluginItemStatus](docs/PluginItemStatus.md)
 - [PluginStatusType](docs/PluginStatusType.md)
 - [Plugins](docs/Plugins.md)
 - [Prediction](docs/Prediction.md)
 - [Prim](docs/Prim.md)
 - [Prim1](docs/Prim1.md)
 - [PrimType](docs/PrimType.md)
 - [Priority](docs/Priority.md)
 - [ProcessingTimestamp](docs/ProcessingTimestamp.md)
 - [Query](docs/Query.md)
 - [RRFConfig](docs/RRFConfig.md)
 - [SceneSummaryResponse](docs/SceneSummaryResponse.md)
 - [ScoreExplanation](docs/ScoreExplanation.md)
 - [ScoringConfig](docs/ScoringConfig.md)
 - [SearchMethod](docs/SearchMethod.md)
 - [SearchResponse](docs/SearchResponse.md)
 - [SearchResultMetadata](docs/SearchResultMetadata.md)
 - [SearchType](docs/SearchType.md)
 - [SpatialQueryResponseItem](docs/SpatialQueryResponseItem.md)
 - [StatsResponse](docs/StatsResponse.md)
 - [StatusResult](docs/StatusResult.md)
 - [StorageBackendInfo](docs/StorageBackendInfo.md)
 - [StorageBackendItemInfo](docs/StorageBackendItemInfo.md)
 - [TextMatchType](docs/TextMatchType.md)
 - [TransactionId](docs/TransactionId.md)
 - [UniqueKey](docs/UniqueKey.md)
 - [UniqueValue](docs/UniqueValue.md)
 - [UsdPath](docs/UsdPath.md)
 - [ValidationError](docs/ValidationError.md)
 - [VectorFieldConfig](docs/VectorFieldConfig.md)
 - [VectorQuery](docs/VectorQuery.md)
 - [VectorQueryType](docs/VectorQueryType.md)
 - [VectorScore](docs/VectorScore.md)
 - [VerifyAccessRequest](docs/VerifyAccessRequest.md)

## Documentation For Authorization

Authentication schemes defined for the API:

### HTTPBearer

- **Type**: Bearer authentication

### HTTPBasic

- **Type**: HTTP basic authentication

### APIKeyHeader

- **Type**: API key
- **API key parameter name**: x-api-key
- **Location**: HTTP header

