# Search Library API Reference

## AssetLibrary

The main entry point. Create an instance, register one or more sources, then run searches against them.

### Constructor

| Parameter | Type | Description |
|---|---|---|
| `log_func` | `Optional[Callable[[int, str], None]]` | Callback that receives all library log output. Levels: 0 = info, 1 = warning, 2 = error. When `None`, messages print to stdout. |
| `raise_on_network_error` | `bool` | When `True`, network failures raise an `AssetLibraryNetworkError` subclass instead of being logged and skipped. Default `False`. |

### Source Management

#### `add_cache_source` *(async)*

Load a local workspace cache described by a `project_config.toml` file and register it as a searchable source. Returns a `CacheSearchSource`.

| Parameter | Type | Description |
|---|---|---|
| `project_config_toml_path` | `str` | Path to the `project_config.toml` file. |
| `file_reader` | `Optional[Callable[[str], str]]` | Optional function used to read file contents instead of the default filesystem reader. |
| `load_completed_callback` | `Optional[Callable[[], None]]` | Called once loading finishes. |

#### `add_s3_source` *(async)*

Load a remote workspace cache described by a `project_config.toml` in an S3 bucket and register it as a searchable source. Returns a `CacheSearchSource`.

| Parameter | Type | Description |
|---|---|---|
| `bucket_url` | `str` | S3 URL in the form `s3://bucket/path/to/simready/root`. |
| `raise_on_network_error` | `Optional[bool]` | Override the instance-level `raise_on_network_error` setting for this call. |

#### `add_indexed_source` *(async)*

Build a filepath index of a directory and register it as a searchable source. Indexed sources contain no asset metadata, so metadata-based filters will produce unexpected results against them. Returns an `IndexedSearchSource`.

| Parameter | Type | Description |
|---|---|---|
| `directory_path` | `str` | Local filesystem path or S3 URL to index. |
| `directory_type` | `str` | `"local"` for a local path, `"s3"` for an S3 URL. |

#### `add_service_source`

Register a remote USD Search API endpoint as a searchable source. Returns a `ServiceSearchSource`.

| Parameter | Type | Description |
|---|---|---|
| `endpoint_url` | `str` | URL of the USD Search service endpoint. |

#### `is_loading`

Return `True` if any registered source is still loading or indexing. Takes no parameters.

#### `cancel_loading`

Cancel any in-progress loading or indexing across all sources without removing them. Takes no parameters.

#### `entry_count`

Return the total number of cached asset entries across all dict-backed sources. Takes no parameters.

#### `remove_source`

Remove a previously registered source by its identifier. Returns `True` if the source was found and removed.

| Parameter | Type | Description |
|---|---|---|
| `source_id` | `str` | Identifier of the source to remove. |

#### `clear_sources`

Remove and cancel loading for all registered sources. Takes no parameters.

### Search

#### `search`

Search all registered sources and return a `List[AssetData]` of matching assets.

| Parameter | Type | Description |
|---|---|---|
| `include_all` | `Optional[List[AssetLibrarySearchFilter]]` | Every filter in this list must match for an asset to be included. |
| `include_any` | `Optional[List[AssetLibrarySearchFilter]]` | At least one filter in this list must match for an asset to be included. |
| `exclude_all` | `Optional[List[AssetLibrarySearchFilter]]` | If every filter in this list matches, the asset is excluded. |
| `exclude_any` | `Optional[List[AssetLibrarySearchFilter]]` | If any filter in this list matches, the asset is excluded. |
| `remove_duplicates` | `bool` | When `True` (default), only the highest-priority version of each asset path is returned. |
| `base_paths` | `Optional[List[str]]` | Restrict results to assets whose absolute path falls under one of these prefixes. |

---

## AssetData

Dataclass returned by `AssetLibrary.search()` representing a single matched asset.

| Field | Type | Description |
|---|---|---|
| `asset_path` | `str` | Absolute path or URL to the asset. |
| `asset_rel_path` | `str` | Path relative to the content root. |
| `asset_version` | `str` | Version string (e.g. `"20250101_120000"`), or `None` for unversioned assets. |
| `tags` | `list[str]` | Flattened list of tag strings aggregated from all tag categories. |
| `source_id` | `str` | Identifier of the source that provided this result. |
| `relevance_score` | `Optional[float]` | Relevance score from a service source, or `None` for local/cache results. |

---

## Search Filters

All filters inherit from the base class `AssetLibrarySearchFilter` and can be passed to the `include_*` / `exclude_*` parameters of `AssetLibrary.search()`.

### `SearchFilterPathContains`

Match assets whose path contains a substring (case-insensitive).

| Parameter | Type | Description |
|---|---|---|
| `substring` | `str` | The substring to search for in the asset path. |

### `SearchFilterPhrase`

An arbitrary natural-language phrase describing the desired asset. Only effective against service sources backed by AI.

| Parameter | Type | Description |
|---|---|---|
| `phrase` | `str` | Free-text description of the desired asset. |

### `SearchFilterClass`

Match assets whose `tags.class` metadata contains a given class name.

| Parameter | Type | Description |
|---|---|---|
| `class_name` | `str` | The class name to match. |

### `SearchFilterTag`

Match assets that have a given tag in any tag namespace.

| Parameter | Type | Description |
|---|---|---|
| `tag` | `str` | The tag string to match. |

### `SearchFilterFeature`

Match assets that have **passed** validation for a given feature.

| Parameter | Type | Description |
|---|---|---|
| `feature` | `str` | Feature name or glob pattern to match. |
| `version` | `str` | When provided, only this specific feature version matches. Defaults to `""` (any version). |
| `case_sensitive` | `bool` | Whether the pattern match is case-sensitive. Defaults to `False`. |

### `SearchFilterProfile`

Match assets whose validation profile name matches a pattern.

| Parameter | Type | Description |
|---|---|---|
| `profile` | `str` | Profile name or glob pattern to match. |
| `version` | `str` | When provided, the profile version must also match. Defaults to `""` (any version). |
| `case_sensitive` | `bool` | Whether the pattern match is case-sensitive. Defaults to `False`. |

### `SearchFilterScenePOI`

Match assets that have a point-of-interest anchor tagged with a given tag.

| Parameter | Type | Description |
|---|---|---|
| `poi_tag` | `str` | The POI tag to match. |

### `SearchFilterCountry`

Match assets associated with a given country.

| Parameter | Type | Description |
|---|---|---|
| `country_name` | `str` | The country name to match. |

### `SearchFilterHeight`

Match assets whose `height` metadata falls within a range.

| Parameter | Type | Description |
|---|---|---|
| `minimum` | `float` | Lower bound of the height range in meters. Defaults to `0.0`. |
| `maximum` | `float` | Upper bound of the height range in meters. Defaults to `inf`. |

### `SearchFilterArbitraryDictValue`

Match assets where traversing the metadata dictionary along a key path yields a specific value. For example, `SearchFilterArbitraryDictValue(["validation", "profile"], "SimReady")` matches `asset_data["validation"]["profile"] == "SimReady"`.

| Parameter | Type | Description |
|---|---|---|
| `dict_path` | `list[str]` | Ordered list of dictionary keys to traverse. |
| `value` | `str` | The expected value at the end of the key path. |

### `SearchFilterRelevance`

Match assets whose relevance score meets a minimum threshold. Only effective against service sources backed by AI; results from index/cache sources always pass.

| Parameter | Type | Description |
|---|---|---|
| `minimum` | `float` | Minimum relevance score. Defaults to `0.0`. |

---

## Exceptions

All exceptions inherit from `AssetLibraryNetworkError`, which inherits from `RuntimeError`. They are only raised when `raise_on_network_error=True`.

| Exception | Description |
|---|---|
| `AssetLibraryNetworkError` | General network or remote call failure. |
| `AssetLibraryTimeoutError` | A network operation timed out. |
| `AssetLibraryConnectionError` | A connection could not be established or was dropped. |
| `AssetLibraryRemoteResponseError` | A remote service returned an invalid or failed response. |

---

## Logging

### `AssetLibrary_LogCallback`

Type alias for `Callable[[int, str], None]`. Pass a callback matching this signature to the `AssetLibrary` constructor or call `set_log_func()` directly to capture log output.

| Level | Meaning |
|---|---|
| 0 | Info |
| 1 | Warning |
| 2 | Error |
