@magic6/dsh-web-fallback-chain 0.0.0-stage → 0.2.4
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/CHANGELOG.md +57 -0
- package/LICENSE +21 -0
- package/README.md +245 -2
- package/README.zh-CN.md +213 -0
- package/cordis.patch.yml +24 -0
- package/icon.svg +15 -0
- package/locale/en.json +6 -0
- package/locale/zh.json +6 -0
- package/package.json +81 -4
- package/src/chains/fetch-plugin.js +213 -0
- package/src/chains/fetch.js +224 -0
- package/src/chains/search-plugin.js +108 -0
- package/src/chains/search.js +159 -0
- package/src/client.js +1655 -0
- package/src/config.js +245 -0
- package/src/index.js +137 -0
- package/src/policy/index.js +37 -0
- package/src/policy/modes.js +179 -0
- package/src/policy/providers.js +191 -0
- package/src/prompt.js +104 -0
- package/src/providers/http.js +213 -0
- package/src/providers/index.js +65 -0
- package/src/providers/vendors.js +309 -0
|
@@ -0,0 +1,159 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Search-chain execution: run the legs in order, take the first real answer.
|
|
3
|
+
*
|
|
4
|
+
* The search-side counterpart of `./fetch.js`. It differs in two ways that matter:
|
|
5
|
+
* an empty `sources[]` is a **miss** rather than a success (a leg answering 200
|
|
6
|
+
* with nothing would otherwise stop the chain), and the provenance marker goes on
|
|
7
|
+
* the first source's snippet — a search result has no single body, and the first
|
|
8
|
+
* snippet is where an answer's lead usually is.
|
|
9
|
+
*
|
|
10
|
+
* @module dsh-web-fallback-chain/chains/search
|
|
11
|
+
*/
|
|
12
|
+
|
|
13
|
+
/** Shorten a message for the attempt record. */
|
|
14
|
+
function shorten(value) {
|
|
15
|
+
const text = String(value ?? '')
|
|
16
|
+
return text.length > 300 ? `${text.slice(0, 300)}…` : text
|
|
17
|
+
}
|
|
18
|
+
|
|
19
|
+
/** Machine-routable code of a failure. */
|
|
20
|
+
function codeOf(error) {
|
|
21
|
+
return typeof error?.code === 'string' && error.code.length > 0 ? error.code : 'WEB_PROVIDER_ERROR'
|
|
22
|
+
}
|
|
23
|
+
|
|
24
|
+
/** One attempt, rendered for the marker and the error. */
|
|
25
|
+
export function describeAttempts(attempts) {
|
|
26
|
+
return attempts
|
|
27
|
+
.map((a) => `${a.leg}=${a.outcome}${a.code ? `(${a.code})` : ''}${a.count !== undefined ? `[${a.count}]` : ''}`)
|
|
28
|
+
.join(', ')
|
|
29
|
+
}
|
|
30
|
+
|
|
31
|
+
import { capText } from '../policy/index.js'
|
|
32
|
+
|
|
33
|
+
/**
|
|
34
|
+
* Cap every source's text to the mode's budget.
|
|
35
|
+
*
|
|
36
|
+
* Applied here rather than in the leg so all legs obey one rule: a leg that
|
|
37
|
+
* returns more than the mode asked for must not cost the caller more context.
|
|
38
|
+
*
|
|
39
|
+
* @param result - a search result (`{sources[], truncated?}`).
|
|
40
|
+
* @param cap - per-source character budget, or null for none.
|
|
41
|
+
* @returns the result with sources capped and `truncated` widened if needed.
|
|
42
|
+
*/
|
|
43
|
+
export function capSources(result, cap) {
|
|
44
|
+
if (cap === null || cap === undefined || !Array.isArray(result?.sources)) return result
|
|
45
|
+
let changed = false
|
|
46
|
+
const sources = result.sources.map((source) => {
|
|
47
|
+
const { text, truncated } = capText(source?.snippet ?? source?.text ?? '', cap)
|
|
48
|
+
if (!truncated) return source
|
|
49
|
+
changed = true
|
|
50
|
+
return { ...source, snippet: text, ...(source.text === undefined ? {} : { text }) }
|
|
51
|
+
})
|
|
52
|
+
return changed ? { ...result, sources, truncated: result.truncated === true } : result
|
|
53
|
+
}
|
|
54
|
+
|
|
55
|
+
/**
|
|
56
|
+
* Append the provenance marker to the first source's text.
|
|
57
|
+
*
|
|
58
|
+
* A search result has no single body: the truthful place to record "this answer
|
|
59
|
+
* came from the third-choice index" is the material the model reads, so the
|
|
60
|
+
* marker goes onto the first source's snippet, which is where an answer's lead
|
|
61
|
+
* usually is. Kept to one short line for the same reason the fetch chain does.
|
|
62
|
+
*
|
|
63
|
+
* @param result - the winning result.
|
|
64
|
+
* @param attempts - every attempt, winner last.
|
|
65
|
+
* @param annotate - whether to append.
|
|
66
|
+
* @returns the result, annotated when a fallback happened.
|
|
67
|
+
*/
|
|
68
|
+
export function finalize(result, attempts, annotate) {
|
|
69
|
+
if (!annotate || attempts.length <= 1 || !Array.isArray(result?.sources) || result.sources.length === 0) return result
|
|
70
|
+
const winner = attempts[attempts.length - 1].leg
|
|
71
|
+
const earlier = describeAttempts(attempts.slice(0, -1))
|
|
72
|
+
const marker = `\n\n---\n[search-chain] these results came from the "${winner}" leg; earlier legs did not serve: ${earlier}`
|
|
73
|
+
const [first, ...rest] = result.sources
|
|
74
|
+
const key = first.snippet === undefined ? 'text' : 'snippet'
|
|
75
|
+
return { ...result, sources: [{ ...first, [key]: `${first[key] ?? ''}${marker}` }, ...rest] }
|
|
76
|
+
}
|
|
77
|
+
|
|
78
|
+
/**
|
|
79
|
+
* Run the legs in order and return the first result that has sources.
|
|
80
|
+
*
|
|
81
|
+
* An empty `sources[]` is a miss, not a success: a search leg answering 200 with
|
|
82
|
+
* zero results would otherwise stop the chain and leave the caller with nothing.
|
|
83
|
+
*
|
|
84
|
+
* @param legs - resolved legs, in order.
|
|
85
|
+
* @param missing - configured ids with no registered provider.
|
|
86
|
+
* @param options - `{annotateFallback, cap}`.
|
|
87
|
+
* @param request - the seam's search request.
|
|
88
|
+
* @param signal - cancellation signal forwarded to every leg.
|
|
89
|
+
* @returns the winning result.
|
|
90
|
+
* @throws a `WebError`-shaped error carrying `attempts` when nothing served.
|
|
91
|
+
*/
|
|
92
|
+
export async function runSearchChain(legs, missing, options, request, signal) {
|
|
93
|
+
const attempts = missing.map((id) => ({ leg: id, outcome: 'unregistered', code: 'WEB_PROVIDER_CONFIGURED_MISSING' }))
|
|
94
|
+
if (legs.length === 0) {
|
|
95
|
+
const error = new Error(
|
|
96
|
+
`web search chain has no usable leg for "${request?.query ?? ''}": ${describeAttempts(attempts) || 'none configured'}`,
|
|
97
|
+
)
|
|
98
|
+
error.code = 'WEB_PROVIDER_UNAVAILABLE'
|
|
99
|
+
error.attempts = attempts
|
|
100
|
+
throw error
|
|
101
|
+
}
|
|
102
|
+
let firstError
|
|
103
|
+
for (const leg of legs) {
|
|
104
|
+
let usable = false
|
|
105
|
+
try {
|
|
106
|
+
usable = leg.provider.available() === true
|
|
107
|
+
} catch (error) {
|
|
108
|
+
attempts.push({ leg: leg.label, outcome: 'unavailable', code: codeOf(error), message: shorten(error?.message) })
|
|
109
|
+
continue
|
|
110
|
+
}
|
|
111
|
+
if (!usable) {
|
|
112
|
+
attempts.push({ leg: leg.label, outcome: 'unavailable', code: 'WEB_PROVIDER_UNAVAILABLE' })
|
|
113
|
+
continue
|
|
114
|
+
}
|
|
115
|
+
try {
|
|
116
|
+
const raw = await leg.provider.search(request, signal)
|
|
117
|
+
const count = Array.isArray(raw?.sources) ? raw.sources.length : 0
|
|
118
|
+
if (count === 0) {
|
|
119
|
+
attempts.push({ leg: leg.label, outcome: 'empty', code: 'WEB_PROVIDER_EMPTY' })
|
|
120
|
+
continue
|
|
121
|
+
}
|
|
122
|
+
attempts.push({ leg: leg.label, outcome: 'served', count })
|
|
123
|
+
return finalize(capSources(raw, options?.cap), attempts, options?.annotateFallback !== false)
|
|
124
|
+
} catch (error) {
|
|
125
|
+
attempts.push({ leg: leg.label, outcome: 'failed', code: codeOf(error), message: shorten(error?.message) })
|
|
126
|
+
if (firstError === undefined) firstError = error
|
|
127
|
+
if (signal?.aborted) throw error
|
|
128
|
+
}
|
|
129
|
+
}
|
|
130
|
+
const error = new Error(
|
|
131
|
+
`web search chain failed for "${request?.query ?? ''}": ${describeAttempts(attempts)}`,
|
|
132
|
+
)
|
|
133
|
+
error.code = attempts.some((a) => a.outcome === 'failed') ? 'WEB_PROVIDER_ERROR' : 'WEB_PROVIDER_UNAVAILABLE'
|
|
134
|
+
error.attempts = attempts
|
|
135
|
+
if (firstError !== undefined) error.cause = firstError
|
|
136
|
+
throw error
|
|
137
|
+
}
|
|
138
|
+
|
|
139
|
+
/** Resolve configured ids against the live registry, reporting misses. */
|
|
140
|
+
export function resolveLegs(registry, order, selfId) {
|
|
141
|
+
const legs = []
|
|
142
|
+
const missing = []
|
|
143
|
+
for (const id of order ?? []) {
|
|
144
|
+
if (id === selfId) {
|
|
145
|
+
throw Object.assign(new Error(`web search chain cannot include itself ("${selfId}")`), { code: 'WEB_PROVIDER_ERROR' })
|
|
146
|
+
}
|
|
147
|
+
const provider = registry?.get?.(id)
|
|
148
|
+
if (provider === undefined) missing.push(id)
|
|
149
|
+
else legs.push({ label: id, provider })
|
|
150
|
+
}
|
|
151
|
+
return { legs, missing }
|
|
152
|
+
}
|
|
153
|
+
|
|
154
|
+
/**
|
|
155
|
+
* Register the chain with `ctx.web`.
|
|
156
|
+
*
|
|
157
|
+
* @param ctx - context whose `web` service receives the provider.
|
|
158
|
+
* @param config - resolved plugin configuration (values or volatile getters).
|
|
159
|
+
*/
|