Request‑ShpEmbedding

SYNOPSIS

Generates embedding vectors for one or more pieces of text.

SYNTAX

Request-ShpEmbedding [-Text] <String[]> [[-Model] <String>] [[-TokenPath] <String>] [[-GitHubHost] <String>]
 [[-EditorVersion] <String>] [[-PluginVersion] <String>] [[-UserAgent] <String>] [[-IntegrationId] <String>]
 [[-TimeoutSec] <Int32>] [[-MaxRetryCount] <Int32>] [[-RetryDelaySec] <Int32>]
 [[-NetworkOutageToleranceSec] <Int32>] [<CommonParameters>]

DESCRIPTION

Posts the supplied text to the resolved backend's embeddings endpoint and returns one object per input carrying its vector. Combine the vectors with Get-ShpCosineSimilarity to rank texts by semantic similarity for search or retrieval-augmented prompting. Text can be supplied from the pipeline; all inputs are sent in a single request. If the backend does not expose an embeddings endpoint the call throws with a clear message.

Credentials follow the backend. The default Copilot backend exchanges a Session token as it always has. An Alternative backend (Set-ShpContext -ApiBase / SHELLPILOT_API_BASE) reads no OAuth token and exchanges no Session token, so no Copilot credential can reach it, and an embedding against a local endpoint needs no GitHub sign-in at all.

EXAMPLES

EXAMPLE 1

Request-ShpEmbedding -Text 'PowerShell is a shell and scripting language.'

Returns the embedding vector for the sentence.

EXAMPLE 2

Get-Content .\docs.txt | Request-ShpEmbedding -Model text-embedding-3-large

Embeds each line of a file using a specific model.

PARAMETERS

-EditorVersion

Editor-Version header value sent with the request.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 5
Default value: $script:DefaultEditorVersion
Accept pipeline input: False
Accept wildcard characters: False

-GitHubHost

HTTPS GitHub.com or Enterprise Cloud GHE.com authentication origin. Explicit value wins over Session context and SHELLPILOT_GITHUB_HOST. The service-returned API endpoint is preserved for the embedding request. Accepted and ignored for an Alternative backend, which authenticates nothing through GitHub.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 4
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-IntegrationId

Copilot-Integration-Id header value sent with the request.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 8
Default value: $script:DefaultIntegrationId
Accept pipeline input: False
Accept wildcard characters: False

-MaxRetryCount

Maximum retries on a transient (429/5xx) HTTP failure. Falls back to the session context and then the built-in default.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 10
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-Model

The embedding model id to use. Defaults to text-embedding-3-small.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 2
Default value: Text-embedding-3-small
Accept pipeline input: False
Accept wildcard characters: False

-NetworkOutageToleranceSec

Wall-clock budget, in seconds, for riding out a connection-level network outage. Falls back to the session context and then the built-in default. 0 disables outage tolerance.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 12
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-PluginVersion

Editor-Plugin-Version header value sent with the request.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 6
Default value: $script:DefaultPluginVersion
Accept pipeline input: False
Accept wildcard characters: False

-RetryDelaySec

Base delay in seconds for the exponential backoff between retries. Falls back to the session context and then the built-in default.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 11
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-Text

One or more strings to embed. Mandatory. Accepts pipeline input.

Type: String[]
Parameter Sets: (All)
Aliases:

Required: True
Position: 1
Default value: None
Accept pipeline input: True (ByValue)
Accept wildcard characters: False

-TimeoutSec

Per-request HTTP timeout in seconds. Falls back to the session context (Set-ShpContext) and then to the built-in default of 0, meaning no explicit timeout.

Type: Int32
Parameter Sets: (All)
Aliases:

Required: False
Position: 9
Default value: 0
Accept pipeline input: False
Accept wildcard characters: False

-TokenPath

Path to an OAuth token file to authenticate with. Omit it to resolve the token by the module's precedence: the session context (Set-ShpContext -GitHubToken), then $env:SHELLPILOT_GITHUB_TOKEN, then the default token file written by Initialize-Shp. Accepted and ignored for an Alternative backend, which needs no GitHub credential.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 3
Default value: None
Accept pipeline input: False
Accept wildcard characters: False

-UserAgent

User-Agent header value sent with the request.

Type: String
Parameter Sets: (All)
Aliases:

Required: False
Position: 7
Default value: $script:DefaultUserAgent
Accept pipeline input: False
Accept wildcard characters: False

CommonParameters

This cmdlet supports the common parameters: -Debug, -ErrorAction, -ErrorVariable, -InformationAction, -InformationVariable, -OutVariable, -OutBuffer, -PipelineVariable, -Verbose, -WarningAction, and -WarningVariable. For more information, see about_CommonParameters.

INPUTS

OUTPUTS

System.Management.Automation.PSCustomObject

One object per input: Index, Text, Embedding (a double array), Model.

NOTES

RELATED LINKS

Get-ShpCosineSimilarity