write-language 0.1.3 → 0.1.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.
Files changed (14) hide show
  1. package/README.md +60 -10
  2. package/package.json +9 -7
  3. package/src/generate-response.ts +196 -196
  4. package/src/generation-types.ts +90 -90
  5. package/src/index.ts +44 -40
  6. package/src/language-model-registry.ts +1336 -1336
  7. package/src/llm-providers.png +0 -0
  8. package/src/prompt-templates.ts +651 -651
  9. package/src/prompts/index.ts +0 -0
  10. package/src/prompts/meta-search-types.ts +7 -0
  11. package/src/prompts/search-prompts.ts +168 -168
  12. package/src/provider-factory.ts +98 -98
  13. package/src/tools/qwksearch-api-tools.ts +327 -0
  14. package/src/utils/markdown-to-html.ts +53 -0
package/README.md CHANGED
@@ -198,14 +198,64 @@ CLOUDFLARE_ACCOUNT_ID=...
198
198
  CLOUDFLARE_API_TOKEN=...
199
199
  ```
200
200
 
201
- ## License
202
201
 
203
- AGPL-3.0
204
-
205
- ## Author
206
-
207
- vtempest <grokthiscontact@gmail.com>
208
-
209
- ## Contributing
210
-
211
- Issues and PRs welcome at [github.com/vtempest/ai-research-agent](https://github.com/vtempest/ai-research-agent)
202
+ ## Model Rank
203
+
204
+
205
+ | Usage | Logo | Flag | Model | Author | Output $/M | Context | Intelligence | Coding | Agentic | Released |
206
+ |---|---|---|---|---|---|---|---|---|---|---|
207
+ | 1 | ![](https://www.google.com/s2/favicons?domain=deepseek.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | DeepSeek V4 Flash | DeepSeek | $0.18 | 1,048,576 | 40.3 | 56.2 | 31.1 | 2mo ago |
208
+ | 2 | ![](https://www.google.com/s2/favicons?domain=xiaomi.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | MiMo-V2.5 | Xiaomi | $0.28 | 1,048,576 | — | — | — | 2mo ago |
209
+ | 3* | ![](https://www.google.com/s2/favicons?domain=minimax.io&sz=64) | ![](https://flagcdn.com/w40/cn.png) | MiniMax M3 | MiniMax | $1.20 | 1,048,576 | 44.4 | 58.6 | 35.4 | 1mo ago |
210
+ | 4* | ![](https://www.google.com/s2/favicons?domain=z.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | GLM 5.2 | Z.ai | $2.856 | 1,048,576 | 51.1 | 68.8 | 43.1 | 2w ago |
211
+ | 5* | ![](https://www.google.com/s2/favicons?domain=tencent.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Hy3 preview | Tencent | $0.21 | 262,144 | — | — | — | 2mo ago |
212
+ | 6* | ![](https://www.google.com/s2/favicons?domain=deepseek.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | DeepSeek V4 Pro | DeepSeek | $0.87 | 1,048,576 | 44.3 | 59.4 | 36.4 | 2mo ago |
213
+ | 7 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Opus 4.7 | Anthropic | $25 | 1,000,000 | 53.5 | 73.6 | 44.4 | 2mo ago |
214
+ | 8 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Opus 4.8 | Anthropic | $25 | 1,000,000 | 55.7 | 74.3 | 47.2 | 1mo ago |
215
+ | 9* | ![](https://www.google.com/s2/favicons?domain=stepfun.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Step 3.7 Flash | StepFun | $1.15 | 256,000 | 29.7 | 37.3 | 21.5 | 1mo ago |
216
+ | 10 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Sonnet 4.6 | Anthropic | $15 | 1,000,000 | 47.2 | 63.0 | 40.8 | 4mo ago |
217
+ | 11* | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-5.5 | OpenAI | $30 | 1,050,000 | 54.8 | 74.9 | 44.9 | 2mo ago |
218
+ | 12* | ![](https://www.google.com/s2/favicons?domain=nvidia.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Nemotron 3 Ultra (free) | NVIDIA | $0 | 1,000,000 | 37.8 | 49.3 | 27.4 | 1mo ago |
219
+ | 13 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 3 Flash Preview | Google | $3 | 1,048,576 | — | — | — | 6mo ago |
220
+ | 14 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Sonnet 5 | Anthropic | $10 | 1,000,000 | 53.4 | 71.5 | 46.7 | 6d ago |
221
+ | 15* | ![](https://www.google.com/s2/favicons?domain=poolside.ai&sz=64) | ![](https://flagcdn.com/w40/us.png) | Laguna M.1 (free) | Poolside | $0 | 262,144 | — | — | — | 2mo ago |
222
+ | 16 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 2.5 Flash Lite | Google | $0.40 | 1,048,576 | — | — | — | 11mo ago |
223
+ | 17 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 2.5 Flash | Google | $2.50 | 1,048,576 | — | — | — | 1y ago |
224
+ | 18* | ![](https://www.google.com/s2/favicons?domain=xiaomi.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | MiMo-V2.5-Pro | Xiaomi | $0.87 | 1,048,576 | 42.2 | 60.2 | 29.1 | 2mo ago |
225
+ | 19 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-4o-mini | OpenAI | $0.60 | 128,000 | — | 11.4 | 1.0 | 1y ago |
226
+ | 20 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 3.1 Flash Lite | Google | $1.50 | 1,048,576 | — | — | — | 2mo ago |
227
+ | 21 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | gpt-oss-120b | OpenAI | $0.15 | 131,072 | 23.8 | 30.4 | 13.2 | 11mo ago |
228
+ | 22 | ![](https://www.google.com/s2/favicons?domain=nvidia.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Nemotron 3 Super (free) | NVIDIA | $0 | 1,000,000 | 25.4 | 37.7 | 8.7 | 3mo ago |
229
+ | 23 | ![](https://www.google.com/s2/favicons?domain=deepseek.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | DeepSeek V3.2 | DeepSeek | $0.3432 | 131,072 | — | 43.7 | — | 7mo ago |
230
+ | 24* | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 3.5 Flash | Google | $9 | 1,048,576 | 50.2 | 70.1 | 37.4 | 1mo ago |
231
+ | 25 | ![](https://www.google.com/s2/favicons?domain=tencent.com&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Hy3 (free) | Tencent | $0 | 262,144 | — | — | — | 0d ago |
232
+ | 26 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-5.4 | OpenAI | $15 | 1,050,000 | 51.4 | 71.1 | 41.1 | 4mo ago |
233
+ | 27 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemma 4 31B | Google | $0.35 | 262,144 | 29.4 | 43.4 | 14.4 | 3mo ago |
234
+ | 28 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemma 4 26B A4B | Google | $0.33 | 262,144 | 25.7 | 39.3 | 11.0 | 3mo ago |
235
+ | 29* | ![](https://www.google.com/s2/favicons?domain=moonshot.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Kimi K2.6 | MoonshotAI | $3.41 | 262,144 | 42.8 | 56.0 | 30.3 | 2mo ago |
236
+ | 30* | ![](https://www.google.com/s2/favicons?domain=mistral.ai&sz=64) | ![](https://flagcdn.com/w40/fr.png) | Mistral Nemo | Mistral | $0.03 | 131,072 | — | — | — | 1y ago |
237
+ | 31* | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Fable 5 | Anthropic | $50 | 1,000,000 | 59.9 | 76.5 | 52.8 | 3w ago |
238
+ | 32 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Opus 4.6 | Anthropic | $25 | 1,000,000 | — | — | — | 5mo ago |
239
+ | 33 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Haiku 4.5 | Anthropic | $5 | 200,000 | 29.6 | 43.9 | 16.4 | 8mo ago |
240
+ | 34 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 3.1 Pro Preview | Google | $12 | 1,048,576 | 46.5 | 68.8 | 21.4 | 4mo ago |
241
+ | 35 | ![](https://www.google.com/s2/favicons?domain=moonshot.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Kimi K2.7 Code | MoonshotAI | $3.50 | 262,144 | 41.9 | 60.8 | 29.6 | 3w ago |
242
+ | 36 | ![](https://www.google.com/s2/favicons?domain=z.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | GLM 5 | Z.ai | $1.92 | 202,752 | — | — | — | 4mo ago |
243
+ | 37 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-5.4 Mini | OpenAI | $4.50 | 400,000 | 40.0 | 56.1 | 30.2 | 3mo ago |
244
+ | 38* | ![](https://www.google.com/s2/favicons?domain=qwen.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Qwen3.7 Max | Qwen | $3.75 | 1,000,000 | 46.0 | 66.0 | 30.6 | 1mo ago |
245
+ | 39 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 3.1 Flash Lite Preview | Google | $1.50 | 1,048,576 | 25.0 | 34.7 | 6.2 | 4mo ago |
246
+ | 40 | ![](https://www.google.com/s2/favicons?domain=qwen.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Qwen3.7 Plus | Qwen | $1.28 | 1,000,000 | 39.0 | 55.9 | 20.8 | 1mo ago |
247
+ | 41* | ![](https://www.google.com/s2/favicons?domain=cohere.com&sz=64) | ![](https://flagcdn.com/w40/ca.png) | North Mini Code (free) | Cohere | $0 | 256,000 | — | 36.5 | — | 2w ago |
248
+ | 42 | ![](https://www.google.com/s2/favicons?domain=z.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | GLM 5.1 | Z.ai | $3.036 | 202,752 | 40.2 | 55.8 | 29.9 | 3mo ago |
249
+ | 43 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-5 Mini | OpenAI | $2 | 400,000 | 25.3 | 15.6 | 19.4 | 11mo ago |
250
+ | 44 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-5.4 Nano | OpenAI | $1.25 | 400,000 | 38.2 | 56.1 | 27.5 | 3mo ago |
251
+ | 45 | ![](https://www.google.com/s2/favicons?domain=minimax.io&sz=64) | ![](https://flagcdn.com/w40/cn.png) | MiniMax M2.7 | MiniMax | $0.72 | 204,800 | 38.1 | 52.6 | 25.6 | 3mo ago |
252
+ | 46 | ![](https://www.google.com/s2/favicons?domain=moonshot.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Kimi K2.5 | MoonshotAI | $2.025 | 262,144 | — | — | — | 5mo ago |
253
+ | 47* | ![](https://www.google.com/s2/favicons?domain=x.ai&sz=64) | ![](https://flagcdn.com/w40/us.png) | Grok 4.3 | xAI | $2.50 | 1,000,000 | 37.6 | 42.2 | 24.1 | 2mo ago |
254
+ | 48 | ![](https://www.google.com/s2/favicons?domain=anthropic.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Claude Sonnet 4.5 | Anthropic | $15 | 1,000,000 | 36.4 | 52.1 | 24.6 | 9mo ago |
255
+ | 49 | ![](https://www.google.com/s2/favicons?domain=google.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | Gemini 2.5 Pro | Google | $10 | 1,048,576 | 25.8 | 33.3 | 7.1 | 1y ago |
256
+ | 50 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | GPT-4.1 Mini | OpenAI | $1.60 | 1,047,576 | 14.8 | 20.2 | 1.7 | 1y ago |
257
+ | 51 | ![](https://www.google.com/s2/favicons?domain=qwen.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Qwen3 235B A22B Instruct 2507 | Qwen | $0.10 | 262,144 | — | — | — | 11mo ago |
258
+ | 52 | ![](https://www.google.com/s2/favicons?domain=poolside.ai&sz=64) | ![](https://flagcdn.com/w40/us.png) | Laguna XS 2.1 (free) | Poolside | $0 | 262,144 | — | — | — | 4d ago |
259
+ | 53 | ![](https://www.google.com/s2/favicons?domain=qwen.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | Qwen3.6 Plus | Qwen | $1.95 | 1,000,000 | 39.6 | 54.5 | 27.6 | 3mo ago |
260
+ | 54 | ![](https://www.google.com/s2/favicons?domain=z.ai&sz=64) | ![](https://flagcdn.com/w40/cn.png) | GLM 4.7 Flash | Z.ai | $0.40 | 202,752 | — | — | — | 5mo ago |
261
+ | 55 | ![](https://www.google.com/s2/favicons?domain=openai.com&sz=64) | ![](https://flagcdn.com/w40/us.png) | gpt-oss-20b | OpenAI | $0.14 | 131,072 | 14.9 | 20.7 | 3.1 | 11mo ago |
package/package.json CHANGED
@@ -1,24 +1,25 @@
1
1
  {
2
2
  "name": "write-language",
3
- "version": "0.1.3",
3
+ "version": "0.1.4",
4
4
  "description": "Multi-provider language generation toolkit using Vercel AI SDK - generate responses with 10+ LLM providers including OpenAI, Anthropic, Google, and more.",
5
5
  "author": "vtempest <grokthiscontact@gmail.com>",
6
6
  "license": "rights.institute/PROSPER",
7
7
  "repository": {
8
8
  "type": "git",
9
- "url": "https://github.com/vtempest/ai-research-agent",
9
+ "url": "https://github.com/OpenSourceAGI/qwksearch-research-agent",
10
10
  "directory": "packages/write-language"
11
11
  },
12
12
  "bugs": {
13
- "url": "https://github.com/vtempest/ai-research-agent/issues"
13
+ "url": "https://github.com/OpenSourceAGI/qwksearch-research-agent/issues"
14
14
  },
15
15
  "main": "./dist/write-language.cjs.js",
16
16
  "types": "./dist/types.d.ts",
17
17
  "exports": {
18
18
  ".": {
19
- "types": "./dist/types.d.ts",
20
- "import": "./dist/write-language.es.js",
21
- "require": "./dist/write-language.cjs.js"
19
+ "types": "./src/index.ts",
20
+ "react-server": "./src/index.ts",
21
+ "import": "./src/index.ts",
22
+ "require": "./src/index.ts"
22
23
  },
23
24
  "./*": {
24
25
  "types": "./src/*.ts",
@@ -81,6 +82,7 @@
81
82
  "highlight.js": "^11.11.1",
82
83
  "html-entities": "^2.6.0",
83
84
  "marked": "^17.0.4",
85
+ "qwksearch-api-client": "^0.0.12",
84
86
  "workers-ai-provider": "^3.1.14",
85
87
  "zod": "^4.3.6"
86
88
  },
@@ -103,4 +105,4 @@
103
105
  "publishConfig": {
104
106
  "access": "public"
105
107
  }
106
- }
108
+ }
package/src/generate-response.ts CHANGED
@@ -1,196 +1,196 @@
1
- /**
2
- * @fileoverview Core logic for generating AI language responses using Vercel AI SDK and various LLM providers.
3
- * Handles prompt interpolation, tool calling, and response formatting.
4
- */
5
- import { generateText, stepCountIs, tool } from "ai";
6
- import { AGENT_PROMPTS } from "./prompt-templates";
7
- import { AGENT_TOOLS } from "../tools/qwksearch-api-tools";
8
- import { LANGUAGE_MODELS, LANGUAGE_PROVIDERS } from "./language-model-registry";
9
- import { createLLMProvider } from "./provider-factory";
10
- import { convertMarkdownToHTMLEscaped } from "../utils/markdown-to-html";
11
- import type {
12
- AgentPrompt,
13
- AgentTool,
14
- GenerateLanguageOptions,
15
- GenerateLanguageResult,
16
- } from "./generation-types";
17
-
18
- export type {
19
- LLMProviderName,
20
- GenerateLanguageOptions,
21
- GenerateLanguageResult,
22
- } from "./generation-types";
23
- export { convertMarkdownToHTMLEscaped } from "../utils/markdown-to-html";
24
-
25
- /**
26
- * ### Generate Language Response
27
- * Writes a language response that shows human-like understanding of the
28
- * question and context.
29
- * - _Requires_: LLM provider, API key, agent name, and context variables.
30
- * - _Providers_: groq, togetherai, openai, anthropic, xai, google,
31
- * perplexity, cloudflare, nvidia
32
- * - _Agent Templates_: custom local entries defined in AGENT_PROMPTS.
33
- * - _How it Works_: Language models predict the most likely next token given
34
- * a prompt. They represent words as high-dimensional vectors, use
35
- * transformer attention across all prior tokens, and sample from the
36
- * resulting probability distribution to produce human-like text.
37
- *
38
- * @see [Vercel AI SDK generateText docs](https://sdk.vercel.ai/docs/reference/ai-sdk-core/generate-text)
39
- * @see [Hugging Face tutorials](https://huggingface.co/learn)
40
- * @see [Illustrated Transformer](https://jalammar.github.io/illustrated-transformer/)
41
- * @see [Building a Transformer with PyTorch](https://www.datacamp.com/tutorial/building-a-transformer-with-py-torch)
42
- * @see [LLM training example](https://github.com/vtempest/ai-research-agent/blob/master/packages/neural-net/src/train/predict-next-word.js)
43
- *
44
- * @param options - Configuration for the language-model call
45
- * @returns Resolved response object with `content`, optional `extract`, or `error`
46
- * @author [Language Model Researchers](https://arc.net/folder/D0472A20-9C20-4D3F-B145-D2865C0A9FEE)
47
- * @example
48
- * const response = await generateLanguageResponse({
49
- * query: "Explain neural networks",
50
- * agent: "question",
51
- * provider: "groq",
52
- * apiKey: "your-api-key",
53
- * });
54
- */
55
- export async function generateLanguageResponse(
56
- options: GenerateLanguageOptions = {} as GenerateLanguageOptions,
57
- ): Promise<GenerateLanguageResult> {
58
- const {
59
- apiKey,
60
- agent = "question",
61
- temperature = 1,
62
- html = true,
63
- applyContextLimit = true,
64
- ...context
65
- } = options;
66
-
67
- // Normalise provider to lowercase for consistent switch matching
68
- const provider = options.provider?.toLowerCase();
69
-
70
- // Resolve model: explicit override \u2192 provider's registered default
71
- const model =
72
- options.model ??
73
- (LANGUAGE_MODELS as Array<{ provider: string; default?: string }>).find(
74
- (m) => m.provider.toLowerCase() === provider,
75
- )?.default ??
76
- "";
77
-
78
- try {
79
- // \u2500\u2500 1. Validate required inputs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
80
- const validProviders = LANGUAGE_PROVIDERS as string[];
81
- if (!apiKey || !provider || !validProviders.includes(provider)) {
82
- return {
83
- error:
84
- "API key and provider are required. Valid providers: " +
85
- validProviders.join(", "),
86
- };
87
- }
88
-
89
- // \u2500\u2500 2. Load agent prompt from local registry \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
90
- const agentObject = (AGENT_PROMPTS as AgentPrompt[]).find(
91
- (p) => p?.name === agent,
92
- );
93
-
94
- if (!agentObject) return { error: `Agent "${agent}" not found` };
95
-
96
- // \u2500\u2500 3. Pre-process the prompt template via optional `before` hook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
97
- if (agentObject.before) {
98
- agentObject.prompt = agentObject.before(agentObject.prompt, options);
99
- }
100
-
101
- // \u2500\u2500 4. Build template variable map and interpolate placeholders \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
102
- const templateVars: Record<string, unknown> = {
103
- ...options,
104
- input: `${context.query ?? ""} ${context.article ?? ""}`,
105
- };
106
- let prompt = interpolateTemplate(agentObject.template ?? "", templateVars);
107
-
108
- // \u2500\u2500 5. Trim prompt to the model's context window \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
109
- if (applyContextLimit) {
110
- const modelConfig = (
111
- LANGUAGE_MODELS as Array<{
112
- provider: string;
113
- models: Array<{ id: string; contextLength: number }>;
114
- }>
115
- )
116
- .find((m) => m.provider.toLowerCase() === provider)
117
- ?.models.find((m) => m.id === model);
118
-
119
- if (modelConfig) {
120
- prompt = prompt.slice(0, modelConfig.contextLength);
121
- }
122
- }
123
-
124
- // \u2500\u2500 6. Instantiate the LLM provider \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
125
- const llm = createLLMProvider(provider, apiKey, model, temperature);
126
- if (!llm) return { error: "Invalid provider selected" };
127
-
128
- // \u2500\u2500 7. Resolve tools declared by the agent \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
129
- const agentToolDefs = (AGENT_TOOLS as AgentTool[]).filter((t) =>
130
- agentObject.tools?.includes(t.name),
131
- );
132
- const tools =
133
- agentToolDefs.length > 0
134
- ? Object.fromEntries(
135
- agentToolDefs.map((t) => [
136
- t.name,
137
- tool({
138
- description: t.description as string,
139
- inputSchema: t.schema as any,
140
- execute: t.func as (args: any) => Promise<string>,
141
- }),
142
- ]),
143
- )
144
- : undefined;
145
-
146
- // \u2500\u2500 8. Invoke LLM via Vercel AI SDK generateText \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
147
- const { text: rawReply } = await generateText({
148
- model: llm,
149
- prompt,
150
- temperature,
151
- ...(tools && { tools, stopWhen: stepCountIs(10) }),
152
- });
153
-
154
- // \u2500\u2500 9. Format output (HTML or raw Markdown) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
155
- const content: string = html
156
- ? await convertMarkdownToHTMLEscaped(rawReply)
157
- : rawReply;
158
-
159
- // \u2500\u2500 10. Extract structured data via optional `after` hook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
160
- const extract = agentObject.after?.(rawReply, options);
161
-
162
- return { content, ...(extract !== undefined && { extract }) };
163
- } catch (err) {
164
- const error = err as { response?: { status?: number }; message?: string };
165
- return {
166
- error:
167
- error.response?.status === 429
168
- ? "Rate limit exceeded. Please wait before trying again."
169
- : (error.message ??
170
- "Failed to generate response. Please try again later."),
171
- };
172
- }
173
- }
174
-
175
- /**
176
- * Substitutes `{variableName}` placeholders in a template string with values
177
- * from `vars`. Object/array values are pretty-printed without braces or
178
- * commas. Unmatched keys fall back to `"[not provided]"`.
179
- *
180
- * @param template - Template string containing `{key}` placeholders
181
- * @param vars - Map of variable names to their replacement values
182
- * @returns The fully interpolated string
183
- */
184
- function interpolateTemplate(
185
- template: string,
186
- vars: Record<string, unknown>,
187
- ): string {
188
- return template.replace(/\{(.+?)\}/g, (_match, key: string) => {
189
- if (!(key in vars)) return "[not provided]";
190
- const value = vars[key];
191
- if (typeof value === "string") return value;
192
- return JSON.stringify(value, null, 2)
193
- .replace(/[{}"]/g, "")
194
- .replace(/,/g, "\n");
195
- });
196
- }
1
+ /**
2
+ * @fileoverview Core logic for generating AI language responses using Vercel AI SDK and various LLM providers.
3
+ * Handles prompt interpolation, tool calling, and response formatting.
4
+ */
5
+ import { generateText, stepCountIs, tool } from "ai";
6
+ import { AGENT_PROMPTS } from "./prompt-templates";
7
+ import { AGENT_TOOLS } from "./tools/qwksearch-api-tools";
8
+ import { LANGUAGE_MODELS, LANGUAGE_PROVIDERS } from "./language-model-registry";
9
+ import { createLLMProvider } from "./provider-factory";
10
+ import { convertMarkdownToHTMLEscaped } from "./utils/markdown-to-html";
11
+ import type {
12
+ AgentPrompt,
13
+ AgentTool,
14
+ GenerateLanguageOptions,
15
+ GenerateLanguageResult,
16
+ } from "./generation-types";
17
+
18
+ export type {
19
+ LLMProviderName,
20
+ GenerateLanguageOptions,
21
+ GenerateLanguageResult,
22
+ } from "./generation-types";
23
+ export { convertMarkdownToHTMLEscaped } from "./utils/markdown-to-html";
24
+
25
+ /**
26
+ * ### Generate Language Response
27
+ * Writes a language response that shows human-like understanding of the
28
+ * question and context.
29
+ * - _Requires_: LLM provider, API key, agent name, and context variables.
30
+ * - _Providers_: groq, togetherai, openai, anthropic, xai, google,
31
+ * perplexity, cloudflare, nvidia
32
+ * - _Agent Templates_: custom local entries defined in AGENT_PROMPTS.
33
+ * - _How it Works_: Language models predict the most likely next token given
34
+ * a prompt. They represent words as high-dimensional vectors, use
35
+ * transformer attention across all prior tokens, and sample from the
36
+ * resulting probability distribution to produce human-like text.
37
+ *
38
+ * @see [Vercel AI SDK generateText docs](https://sdk.vercel.ai/docs/reference/ai-sdk-core/generate-text)
39
+ * @see [Hugging Face tutorials](https://huggingface.co/learn)
40
+ * @see [Illustrated Transformer](https://jalammar.github.io/illustrated-transformer/)
41
+ * @see [Building a Transformer with PyTorch](https://www.datacamp.com/tutorial/building-a-transformer-with-py-torch)
42
+ * @see [LLM training example](https://github.com/vtempest/ai-research-agent/blob/master/packages/neural-net/src/train/predict-next-word.js)
43
+ *
44
+ * @param options - Configuration for the language-model call
45
+ * @returns Resolved response object with `content`, optional `extract`, or `error`
46
+ * @author [Language Model Researchers](https://arc.net/folder/D0472A20-9C20-4D3F-B145-D2865C0A9FEE)
47
+ * @example
48
+ * const response = await generateLanguageResponse({
49
+ * query: "Explain neural networks",
50
+ * agent: "question",
51
+ * provider: "groq",
52
+ * apiKey: "your-api-key",
53
+ * });
54
+ */
55
+ export async function generateLanguageResponse(
56
+ options: GenerateLanguageOptions = {} as GenerateLanguageOptions,
57
+ ): Promise<GenerateLanguageResult> {
58
+ const {
59
+ apiKey,
60
+ agent = "question",
61
+ temperature = 1,
62
+ html = true,
63
+ applyContextLimit = true,
64
+ ...context
65
+ } = options;
66
+
67
+ // Normalise provider to lowercase for consistent switch matching
68
+ const provider = options.provider?.toLowerCase();
69
+
70
+ // Resolve model: explicit override \u2192 provider's registered default
71
+ const model =
72
+ options.model ??
73
+ (LANGUAGE_MODELS as Array<{ provider: string; default?: string }>).find(
74
+ (m) => m.provider.toLowerCase() === provider,
75
+ )?.default ??
76
+ "";
77
+
78
+ try {
79
+ // \u2500\u2500 1. Validate required inputs \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
80
+ const validProviders = LANGUAGE_PROVIDERS as string[];
81
+ if (!apiKey || !provider || !validProviders.includes(provider)) {
82
+ return {
83
+ error:
84
+ "API key and provider are required. Valid providers: " +
85
+ validProviders.join(", "),
86
+ };
87
+ }
88
+
89
+ // \u2500\u2500 2. Load agent prompt from local registry \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
90
+ const agentObject = (AGENT_PROMPTS as AgentPrompt[]).find(
91
+ (p) => p?.name === agent,
92
+ );
93
+
94
+ if (!agentObject) return { error: `Agent "${agent}" not found` };
95
+
96
+ // \u2500\u2500 3. Pre-process the prompt template via optional `before` hook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
97
+ if (agentObject.before) {
98
+ agentObject.prompt = agentObject.before(agentObject.prompt, options);
99
+ }
100
+
101
+ // \u2500\u2500 4. Build template variable map and interpolate placeholders \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
102
+ const templateVars: Record<string, unknown> = {
103
+ ...options,
104
+ input: `${context.query ?? ""} ${context.article ?? ""}`,
105
+ };
106
+ let prompt = interpolateTemplate(agentObject.template ?? "", templateVars);
107
+
108
+ // \u2500\u2500 5. Trim prompt to the model's context window \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
109
+ if (applyContextLimit) {
110
+ const modelConfig = (
111
+ LANGUAGE_MODELS as Array<{
112
+ provider: string;
113
+ models: Array<{ id: string; contextLength: number }>;
114
+ }>
115
+ )
116
+ .find((m) => m.provider.toLowerCase() === provider)
117
+ ?.models.find((m) => m.id === model);
118
+
119
+ if (modelConfig) {
120
+ prompt = prompt.slice(0, modelConfig.contextLength);
121
+ }
122
+ }
123
+
124
+ // \u2500\u2500 6. Instantiate the LLM provider \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
125
+ const llm = createLLMProvider(provider, apiKey, model, temperature);
126
+ if (!llm) return { error: "Invalid provider selected" };
127
+
128
+ // \u2500\u2500 7. Resolve tools declared by the agent \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
129
+ const agentToolDefs = (AGENT_TOOLS as AgentTool[]).filter((t) =>
130
+ agentObject.tools?.includes(t.name),
131
+ );
132
+ const tools =
133
+ agentToolDefs.length > 0
134
+ ? Object.fromEntries(
135
+ agentToolDefs.map((t) => [
136
+ t.name,
137
+ tool({
138
+ description: t.description as string,
139
+ inputSchema: t.schema as any,
140
+ execute: t.func as (args: any) => Promise<string>,
141
+ }),
142
+ ]),
143
+ )
144
+ : undefined;
145
+
146
+ // \u2500\u2500 8. Invoke LLM via Vercel AI SDK generateText \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
147
+ const { text: rawReply } = await generateText({
148
+ model: llm,
149
+ prompt,
150
+ temperature,
151
+ ...(tools && { tools, stopWhen: stepCountIs(10) }),
152
+ });
153
+
154
+ // \u2500\u2500 9. Format output (HTML or raw Markdown) \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
155
+ const content: string = html
156
+ ? await convertMarkdownToHTMLEscaped(rawReply)
157
+ : rawReply;
158
+
159
+ // \u2500\u2500 10. Extract structured data via optional `after` hook \u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500\u2500
160
+ const extract = agentObject.after?.(rawReply, options);
161
+
162
+ return { content, ...(extract !== undefined && { extract }) };
163
+ } catch (err) {
164
+ const error = err as { response?: { status?: number }; message?: string };
165
+ return {
166
+ error:
167
+ error.response?.status === 429
168
+ ? "Rate limit exceeded. Please wait before trying again."
169
+ : (error.message ??
170
+ "Failed to generate response. Please try again later."),
171
+ };
172
+ }
173
+ }
174
+
175
+ /**
176
+ * Substitutes `{variableName}` placeholders in a template string with values
177
+ * from `vars`. Object/array values are pretty-printed without braces or
178
+ * commas. Unmatched keys fall back to `"[not provided]"`.
179
+ *
180
+ * @param template - Template string containing `{key}` placeholders
181
+ * @param vars - Map of variable names to their replacement values
182
+ * @returns The fully interpolated string
183
+ */
184
+ function interpolateTemplate(
185
+ template: string,
186
+ vars: Record<string, unknown>,
187
+ ): string {
188
+ return template.replace(/\{(.+?)\}/g, (_match, key: string) => {
189
+ if (!(key in vars)) return "[not provided]";
190
+ const value = vars[key];
191
+ if (typeof value === "string") return value;
192
+ return JSON.stringify(value, null, 2)
193
+ .replace(/[{}"]/g, "")
194
+ .replace(/,/g, "\n");
195
+ });
196
+ }