diff --git a/docs/dir/scenarios.md b/docs/dir/scenarios.md index 041bf627..e37a9a99 100644 --- a/docs/dir/scenarios.md +++ b/docs/dir/scenarios.md @@ -1,7 +1,7 @@ # Usage Scenarios This document defines a basic overview of main Directory features, components, and usage scenarios. -All code snippets below are tested against the Directory `v0.2.0` release. +All code snippets below are tested against the Directory `v0.3.0` release. !!! note Although the following example is shown for a CLI-based usage scenario, there is an effort to expose the same functionality via language-specific SDKs. @@ -24,7 +24,7 @@ cat << EOF > record.json "name": "record", "version": "v1.0.0", "description": "insert description here", - "schema_version": "v0.5.0", + "schema_version": "v0.7.0", "skills": [ { "id": 302, @@ -48,7 +48,7 @@ EOF ### Store This example demonstrates the interaction with the local storage layer using the CLI client. -The storage layer is used as a content-addressable object store for Directory-specific models and serves both the local and network-based operations (if enabled). +The storage layer uses an OCI-compliant registry (powered by Zot) to store records as OCI artifacts with content-addressable identifiers (CIDs). When a record is pushed, it's stored as an OCI blob and the CID is calculated by converting the SHA256 digest from ORAS operations into a CIDv1 format using IPFS multihash encoding. Each record is then tagged with its CID in the registry, enabling direct lookup and ensuring content integrity through cryptographic addressing. ```bash # Push the record and store its CID to a file @@ -130,6 +130,7 @@ dirctl verify $RECORD_CID ### Announce This example demonstrates how to publish records to allow content discovery across the network. +Publication requests are processed asynchronously in the background using a scheduler that manages DHT announcements. To avoid stale data, it is recommended to republish the data periodically as the data across the network has TTL. @@ -137,7 +138,7 @@ Note that this operation only works for the objects already pushed to the local ```bash # Publish the record across the network -dirctl publish $RECORD_CID +dirctl routing publish $RECORD_CID ``` If the data is not published to the network, it cannot be discovered by other peers. @@ -147,50 +148,48 @@ Network publication may fail if you are not connected to the network. ### Discover -This example demonstrates how to discover published data locally or across the network. -The API supports both unicast- mode for routing to specific objects, -and multicast- mode for attribute-based matching and routing. +This example demonstrates how to discover records both locally and across the network using two distinct commands for different use cases. -There are two modes of operation, a) local mode where the data is queried from the local data store, and b) network mode where the data is queried across the network. +#### Local Discovery -Discovery is performed using full-set label matching, i.e., the results always fully match the requested query. -Note that it is not guaranteed that the returned data is available, valid, or up to date. +Use `dirctl routing list` to discover records stored locally on this peer only. This queries the server's local storage index and does not search other peers on the network. ```bash -# Get a list of peers holding a specific record -dirctl list --digest $DIGEST +# List all local records +dirctl routing list -#> Peer 12D3KooWQffoFP8ePUxTeZ8AcfReTMo4oRPqTiN1caDeG5YW3gng -#> Digest: sha256: -#> Labels: /skills/Text Generation, /skills/Fact Extraction +# List local records with specific skill +dirctl routing list --skill "AI" -# Discover the records in your local data store -dirctl list "/skills/Text Generation" -dirctl list "/skills/Text Generation" "/skills/Fact Extraction" +# List records with multiple criteria (AND logic) +dirctl routing list --skill "AI" --locator "docker-image" -#> Peer HOST -#> Digest: sha256: -#> Labels: /skills/Text Generation, /skills/Fact Extraction - -# Discover the records across the network -dirctl list "/skills/Text Generation" --network -dirctl list "/skills/Text Generation" "/skills/Fact Extraction" --network +# List specific record by CID +dirctl routing list --cid $RECORD_CID ``` -It is also possible to get an aggregated summary of the data held in your local data store or across the network. -This is used for routing decisions when traversing the network. +#### Network Discovery + +Use `dirctl routing search` to discover records from other peers across the network. This uses cached network announcements and filters out local records. ```bash -# Get label summary details in your local data store -dirctl list info +# Search for records with exact skill match +dirctl routing search --skill "Natural Language Processing/Text Completion" + +# Search for records with skill prefix match (finds all NLP-related skills) +dirctl routing search --skill "Natural Language Processing" -#> Peer HOST | Label: /skills/Text Generation | Total: 1 -#> Peer HOST | Label: /skills/Fact Extraction | Total: 1 +# Search with multiple criteria (OR logic with minimum score) +dirctl routing search --skill "AI" --skill "ML" --min-score 2 -# Get label summary details across the network -dirctl list info --network +# Search with result limiting +dirctl routing search --skill "AI" --limit 5 ``` +Network search supports hierarchical matching where skills, domains, and features use both exact and prefix matching (e.g., "AI" matches both "/skills/AI" exactly and "/skills/AI/ML" as a prefix). + +Note that network search results are not guaranteed to be available, valid, or up to date as they rely on cached announcements from other peers. + ### Search This example demonstrates how to search for records in the directory using various filters and query parameters.