write-language 0.1.4 → 0.1.6

package/README.md

@@ -34,9 +34,9 @@ npm install write-language
 ### Basic Response Generation
 
 ```typescript
-import { generateLanguageResponse } from 'write-language';
+import { writeLanguageResponse } from 'write-language';
 
-const result = await generateLanguageResponse({
+const result = await writeLanguageResponse({
   provider: 'openai',
   model: 'gpt-4-turbo',
   prompt: 'Explain quantum computing in simple terms',
@@ -49,7 +49,7 @@ console.log(result.text);
 ### Streaming Responses
 
 ```typescript
-const result = await generateLanguageResponse({
+const result = await writeLanguageResponse({
   provider: 'anthropic',
   model: 'claude-3-5-sonnet-20241022',
   prompt: 'Write a short story about AI',
@@ -107,7 +107,7 @@ const model = provider('llama-3.3-70b-versatile');
 ```typescript
 import { AGENT_PROMPTS } from 'write-language';
 
-const result = await generateLanguageResponse({
+const result = await writeLanguageResponse({
   provider: 'openai',
   model: 'gpt-4',
   prompt: AGENT_PROMPTS.researchAgent.systemPrompt,
@@ -132,7 +132,7 @@ const html = convertMarkdownToHTMLEscaped(markdown);
 
 ## API Reference
 
-### `generateLanguageResponse(options)`
+### `writeLanguageResponse(options)`
 
 Generate an AI language response.
 
@@ -168,35 +168,30 @@ Create a provider instance.
 - `getTextOnlyModels()`: Get text-only models
 - `getMultimodalModels()`: Get multimodal models
 
-## Supported Providers
+Multi-provider AI agent toolkit for generating language responses, searching the web, extracting page content, and managing long-term memory across 10+ LLM providers.
 
-| Provider | Models | Capabilities |
-|----------|--------|--------------|
-| OpenAI | GPT-4, GPT-3.5, o1, o3 | Text, Multimodal, Functions |
-| Anthropic | Claude 3.5, Claude 3 | Text, Multimodal, Functions |
-| Google | Gemini 2.0, Gemini 1.5 | Text, Multimodal |
-| AWS Bedrock | Claude, Llama, Mistral | Text, Multimodal |
-| Groq | Llama 3, Mixtral | Text, Fast Inference |
-| xAI | Grok | Text |
-| Cloudflare | Various | Text, Edge Deployment |
-| Ollama | Local Models | Text, Privacy |
-| OpenRouter | 100+ Models | Text, Aggregator |
+Built on top of the [Vercel AI SDK](https://sdk.vercel.ai), with a small registry of pre-tuned agent prompts (research, summarization, citation answering, query resolution, knowledge-graph extraction, etc.) and tool wrappers around the [QwkSearch](https://qwksearch.com) API.
 
-## Environment Variables
+## Language Intelligence Providers
 
-Set API keys for the providers you want to use:
-
-```bash
-OPENAI_API_KEY=sk-...
-ANTHROPIC_API_KEY=sk-ant-...
-GOOGLE_API_KEY=...
-GROQ_API_KEY=gsk_...
-XAI_API_KEY=xai-...
-AWS_ACCESS_KEY_ID=...
-AWS_SECRET_ACCESS_KEY=...
-CLOUDFLARE_ACCOUNT_ID=...
-CLOUDFLARE_API_TOKEN=...
-```
+| Provider               | 🌍  | Top Model (Others)                            | 🏆 Benchmarks                                                         | 📄 Docs                                                                                               | 🔑 Keys                                                                                            | 💰 Funding   |
+| ---------------------- | --- | --------------------------------------------- | --------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------- | ------------ |
+| **Anthropic**          | 🇺🇸  | Claude Mythos / Opus  (Sonnet, Haiku)         | 🥇 GPQA Diamond 94.6% · 🥇 SWE-bench 93.9% · 🧬 PhD reasoning         | [Docs](https://docs.anthropic.com/en/docs/welcome)                                                    | [Keys](https://console.anthropic.com/settings/keys)                                                | ~$60B        |
+| **OpenAI**             | 🇺🇸  | GPT / o3 / Codex (o1, o4, o4-mini, gpt-4o)    | 🥇 AIME 2025 100% · 🥇 SWE-bench Pro · 📚 MMLU-Pro 90%                | [Docs](https://platform.openai.com/docs/overview)                                                     | [Keys](https://platform.openai.com/api-keys)                                                       | ~$180B       |
+| **Google**      | 🇺🇸  | Gemini Pro (Flash, Flash-Lite, Gemma)         | 🥇 GPQA 94.1% · 🥇 LiveCodeBench Elo 2439 · 🌐 #1 in 6/13 Vals        | [Docs](https://cloud.google.com/vertex-ai/generative-ai/docs/learn/models)                            | [Keys](https://cloud.google.com/vertex-ai/generative-ai/docs/start/express-mode/overview#api-keys) | Public       |
+| **xAI**                | 🇺🇸  | Grok Heavy (Grok-3, Grok Vision)              | 🥇 AIME 2025 100% · 🧮 Math competition · ⚡ X integration            | [Docs](https://docs.x.ai/docs#models)                                                                 | [Keys](https://console.x.ai/)                                                                      | ~$45B        |
+| **Meta**               | 🇺🇸  | Llama Maverick / Scout (Llama 3.x, CodeLlama) | 🥇 DocVQA 94.4% · 🥇 10M token context · 📊 ChartQA 90%               | [Docs](https://www.llama.com/docs/overview/)                                                          | [Keys](https://www.llama.com/llama-downloads/)                                                     | Public       |
+| **NVIDIA**             | 🇺🇸  | Nemotron-Cascade  (Llama Nemotron, Kimi)      | 🥇 LCB v6 87.2% · 🏅 IMO+IOI+ICPC gold · 🧮 AIME 98.6%                | [Docs](https://docs.api.nvidia.com/nim/reference/llm-apis)                                            | [Keys](https://build.nvidia.com/settings/api-keys)                                                 | Public       |
+| **Perplexity**      | 🇺🇸  | Sonar Reasoning Pro (Sonar Deep Research)     | 🥇 Search Arena · 🔍 #1 web-grounded QA · 🌐 Real-time retrieval      | [Docs](https://docs.perplexity.ai/models/model-cards)                                                 | [Keys](https://www.perplexity.ai/account/api/keys)                                                 | ~$1B         |
+| **Groq**               | 🇺🇸  | (Llama, DeepSeek, Gemma, Mistral, Qwen)       | ⚡ #1 inference speed · 🏎️ Fastest TTFT · 🔧 LPU hardware             | [Docs](https://console.groq.com/docs/overview)                                                        | [Keys](https://console.groq.com/keys)                                                              | ~$640M       |
+| **Mistral**         | 🇫🇷  | Mistral Large  (Small 4, Codestral, Devstral) | 🥈 Arena Elo 1418 · 🌍 Multilingual MMLU 85.5% · 🚀 Fastest TTFT      | [Docs](https://docs.mistral.ai/)                                                                      | [Keys](https://console.mistral.ai/api-keys/)                                                       | ~$3.1B       |
+| **Together**        | 🇺🇸  | (Llama, Mistral, Gemma, Qwen, DeepSeek)       | 🏗️ Widest open hosting · 💸 Best open-source pricing · 🔧 Fine-tuning | [Docs](https://docs.together.ai/docs/quickstart)                                                      | [Keys](https://api.together.xyz/settings/api-keys)                                                 | ~$225M       |
+| **Moonshot** | 🇨🇳  | Kimi Reasoning (K2.6, K2)                     | 🥇 AIME open 96.1% · 🥇 MATH-500 98% · 🥇 HumanEval 99%               | [Docs](https://platform.moonshot.cn/docs)                                                             | [Keys](https://platform.moonshot.cn/console/api-keys)                                              | ~$3.9B       |
+| **Zhipu**     | 🇨🇳  | GLM Reasoning / GLM-4.7 (GLM-4V, CogView)     | 🥇 Chatbot Arena Elo 1451 · 🥇 MMLU 96% · 🧮 AIME 95.7%               | [Docs](https://bigmodel.cn/dev/api)                                                                   | [Keys](https://bigmodel.cn/usercenter/apikeys)                                                     | ~$1.8B       |
+| **Alibaba**     | 🇨🇳  | Qwen-Coder / Qwen  (Qwen-VL, Qwen-Audio)      | 🥇 Codeforces Elo 2056 · 💻 SWE-bench 69.6% · 🏎️ LCB 70.7%            | [Docs](https://www.alibabacloud.com/help/en/model-studio/developer-reference/use-qwen-by-calling-api) | [Keys](https://bailian.console.aliyun.com/?apiKey=1)                                               | Public       |
+| **DeepSeek**           | 🇨🇳  | DeepSeek (DeepSeek-Coder, DeepSeek-VL)        | 🥇 IMO gold (open) · 📚 MMLU-Pro 81.2 · 🧮 AIME 87.5%                 | [Docs](https://api-docs.deepseek.com/)                                                                | [Keys](https://platform.deepseek.com/api_keys)                                                     | Bootstrapped |
+| **Cloudflare**         | 🇺🇸  | (Llama, Mistral, Gemma, Qwen, DeepSeek)       | 🌐 Edge inference · ⚡ Serverless CDN scale · 🔒 Privacy-first        | [Docs](https://developers.cloudflare.com/workers-ai/)                                                 | [Keys](https://dash.cloudflare.com/profile/api-tokens)                                             | Public       |
+| **Ollama**             | 🇺🇸  | (Llama, Mistral, Gemma, Qwen, DeepSeek)       | 🖥️ #1 local inference · 🔒 Fully offline · 🆓 Free self-hosted        | [Docs](https://ollama.com/docs)                                                                       | [Keys](https://ollama.com/settings/keys)                                                           | ~$20M        |
 
 
 ## Model Rank
@@ -208,7 +203,7 @@ CLOUDFLARE_API_TOKEN=...
 | 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 |
 | 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 |
 | 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 |
-| 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 |
+| 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 | 
 | 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 |
 | 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 |
 | 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 |

package/dist/generate-response.d.ts

@@ -0,0 +1,34 @@
+import { GenerateLanguageOptions, GenerateLanguageResult } from './generation-types';
+export type { LLMProviderName, GenerateLanguageOptions, GenerateLanguageResult, } from './generation-types';
+export { convertMarkdownToHTMLEscaped } from './utils/markdown-to-html';
+/**
+ * ### Generate Language Response
+ * Writes a language response that shows human-like understanding of the
+ * question and context.
+ * - _Requires_: LLM provider, API key, agent name, and context variables.
+ * - _Providers_: groq, togetherai, openai, anthropic, xai, google,
+ *   perplexity, cloudflare, nvidia
+ * - _Agent Templates_: custom local entries defined in AGENT_PROMPTS.
+ * - _How it Works_: Language models predict the most likely next token given
+ *   a prompt. They represent words as high-dimensional vectors, use
+ *   transformer attention across all prior tokens, and sample from the
+ *   resulting probability distribution to produce human-like text.
+ *
+ * @see [Vercel AI SDK generateText docs](https://sdk.vercel.ai/docs/reference/ai-sdk-core/generate-text)
+ * @see [Hugging Face tutorials](https://huggingface.co/learn)
+ * @see [Illustrated Transformer](https://jalammar.github.io/illustrated-transformer/)
+ * @see [Building a Transformer with PyTorch](https://www.datacamp.com/tutorial/building-a-transformer-with-py-torch)
+ * @see [LLM training example](https://github.com/vtempest/ai-research-agent/blob/master/packages/neural-net/src/train/predict-next-word.js)
+ *
+ * @param options - Configuration for the language-model call
+ * @returns Resolved response object with `content`, optional `extract`, or `error`
+ * @author [Language Model Researchers](https://arc.net/folder/D0472A20-9C20-4D3F-B145-D2865C0A9FEE)
+ * @example
+ * const response = await writeLanguageResponse({
+ *   query: "Explain neural networks",
+ *   agent: "question",
+ *   provider: "groq",
+ *   apiKey: "your-api-key",
+ * });
+ */
+export declare function writeLanguageResponse(options?: GenerateLanguageOptions): Promise<GenerateLanguageResult>;

package/dist/generation-types.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @module research/agents/generate-language-types
+ * @description Shared types for the generate-language module.
+ */
+/** Supported LLM provider identifiers */
+export type LLMProviderName = "nvidia" | "openrouter" | "anthropic" | "google" | "openai" | "xai" | "groq" | "cloudflare" | "perplexity" | "amazon" | "bedrock" | "togetherai" | (string & {});
+/**
+ * Configuration options for {@link writeLanguageResponse}.
+ */
+export interface GenerateLanguageOptions {
+    /** LLM provider to use */
+    provider: LLMProviderName;
+    /**
+     * API key for the provider.
+     * For `cloudflare`, use the `"apiToken:accountId"` format.
+     * For `amazon`/`bedrock`, use bearer token or `"region:accessKeyId:secretAccessKey"` format.
+     */
+    apiKey?: string;
+    /** Agent prompt template name (default: `"question"`) */
+    agent?: string;
+    /** Specific model ID. Falls back to the provider's registered default. */
+    model?: string;
+    /**
+     * Sampling temperature (0\u20132).
+     * Lower = more deterministic; higher = more creative. Default: `1`
+     */
+    temperature?: number;
+    /** User query text */
+    query?: string;
+    /** Article or document text to process */
+    article?: string;
+    /** Prior conversation history for context-aware agents */
+    chat_history?: string;
+    /** Return `HTML` (`true`) or raw Markdown (`false`). Default: `true` */
+    html?: boolean;
+    /** Truncate the prompt to the model's context window length. Default: `true` */
+    applyContextLimit?: boolean;
+    /** Additional template variables forwarded to the agent prompt */
+    [key: string]: unknown;
+}
+/** Return value of {@link writeLanguageResponse} */
+export interface GenerateLanguageResult {
+    /** Generated response in HTML or Markdown format */
+    content?: string;
+    /** Structured data extracted by the agent's `after` callback */
+    extract?: unknown;
+    /** Human-readable error message when generation fails */
+    error?: string;
+}
+/** Agent prompt template definition */
+export interface AgentPrompt {
+    name: string;
+    /** Mustache-style template string with `{variableName}` placeholders */
+    template?: string;
+    prompt?: string;
+    /** Called before template substitution to pre-process the prompt */
+    before?: (prompt: string | undefined, options: GenerateLanguageOptions) => string;
+    /** Called after generation to extract structured data from the raw reply */
+    after?: (reply: string, options: GenerateLanguageOptions) => unknown;
+    /** Names of registered agent tools to attach to this agent */
+    tools?: string[];
+}
+/** A registered agent tool with a name, schema, and async handler */
+export interface AgentTool {
+    name: string;
+    func: (...args: unknown[]) => unknown | Promise<unknown>;
+    [key: string]: unknown;
+}

package/dist/index.d.ts

@@ -0,0 +1,20 @@
+/**
+ * @fileoverview Language Generation Module
+ *
+ * Centralized exports for AI language model response generation using Vercel AI SDK.
+ * Provides prompt templates, model registries, provider factories, and response
+ * generation functions for 10+ LLM providers.
+ *
+ * @module language-generation
+ * @author ai-research-agent contributors
+ */
+export { writeLanguageResponse, convertMarkdownToHTMLEscaped, } from './generate-response';
+export type { LLMProviderName, GenerateLanguageOptions, GenerateLanguageResult, } from './generate-response';
+export type { AgentPrompt, AgentTool, } from './generation-types';
+export { AGENT_PROMPTS, extractJSONFromLanguageReply } from './prompt-templates';
+export { LANGUAGE_MODELS, LANGUAGE_PROVIDERS, getModelsByProvider, getAllModels, getModelsByCapability, getTextOnlyModels, getMultimodalModels, } from './language-model-registry';
+export type { ModelCapability, ModelInfo } from './language-model-registry';
+export { createLLMProvider } from './provider-factory';
+export * from './prompts';
+export { AGENT_TOOLS } from './tools/qwksearch-api-tools';
+export { convertMarkdownToHTMLEscaped as markdownToHTML } from './utils/markdown-to-html';

package/dist/language-model-registry.d.ts

@@ -0,0 +1,105 @@
+/**
+ * List of default models for the chat providers and a list of models
+ * @property {string} provider - The provider name
+ * @property {string} docs - The documentation URL for the model
+ * @property {string} api_key - The API key  url for the model
+ * @property {string} default - The default model for the chat provider
+ * @property {Object[]} models - The list of models available for the chat provider
+ * @category Generate
+ */
+export declare const LANGUAGE_MODELS: ({
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+    }[];
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    models: {
+        name: string;
+        id: string;
+        contextLength: number;
+    }[];
+    default?: undefined;
+} | {
+    provider: string;
+    docs: string;
+    api_key: string;
+    default: string;
+    models: ({
+        name: string;
+        id: string;
+        contextLength: number;
+        provider: string;
+        type?: undefined;
+    } | {
+        name: string;
+        id: string;
+        contextLength: number;
+        provider: string;
+        type: string;
+    })[];
+})[];
+/** List of available LLM provider services */
+export declare const LANGUAGE_PROVIDERS: string[];
+/**
+ * Model capability types for filtering
+ */
+export type ModelCapability = "text" | "vision" | "audio" | "code" | "reasoning";
+/**
+ * Extended model information with capabilities
+ */
+export interface ModelInfo {
+    name: string;
+    id: string;
+    contextLength: number;
+    capabilities?: ModelCapability[];
+    provider: string;
+}
+/**
+ * Get all models for a specific provider
+ * @param providerName - Name of the provider (case-insensitive)
+ * @returns Array of models for that provider
+ * @example
+ * const nvidiaModels = getModelsByProvider("nvidia");
+ */
+export declare function getModelsByProvider(providerName: string): ModelInfo[];
+/**
+ * Get all available models across all providers
+ * @returns Array of all models with provider information
+ */
+export declare function getAllModels(): ModelInfo[];
+/**
+ * Filter models by capability (text-only, vision, etc.)
+ * @param capability - The capability to filter by
+ * @param providerName - Optional: filter by specific provider
+ * @returns Array of models with the specified capability
+ * @example
+ * const textOnlyModels = getModelsByCapability("text");
+ * const visionModels = getModelsByCapability("vision", "openai");
+ */
+export declare function getModelsByCapability(capability: ModelCapability, providerName?: string): ModelInfo[];
+/**
+ * Get text-only models (no vision, audio, etc.)
+ * @param providerName - Optional: filter by specific provider
+ * @returns Array of text-only models
+ * @example
+ * const textModels = getTextOnlyModels();
+ * const groqTextModels = getTextOnlyModels("groq");
+ */
+export declare function getTextOnlyModels(providerName?: string): ModelInfo[];
+/**
+ * Get multimodal models (vision, audio, etc.)
+ * @param providerName - Optional: filter by specific provider
+ * @returns Array of multimodal models
+ * @example
+ * const multimodalModels = getMultimodalModels();
+ * const openaiMultimodal = getMultimodalModels("openai");
+ */
+export declare function getMultimodalModels(providerName?: string): ModelInfo[];

package/dist/prompt-templates.d.ts

@@ -0,0 +1,37 @@
+/**
+ * @fileoverview Prompt templates and extraction logic for various AI agents.
+ * Includes templates for research, summarization, query resolution, and more.
+ */
+export declare const AGENT_PROMPTS: ({
+    name: string;
+    template: string;
+    before?: undefined;
+    after?: undefined;
+    tools?: undefined;
+} | {
+    name: string;
+    template: string;
+    before: (prompt: any, params: any) => any;
+    after: any;
+    tools?: undefined;
+} | {
+    name: string;
+    template: string;
+    tools: string[];
+    after: any;
+    before?: undefined;
+} | {
+    name: string;
+    template: string;
+    after: (content: any, options?: {}) => any;
+    before?: undefined;
+    tools?: undefined;
+})[];
+/**
+* Extracts and cleans content between XML-style tags and returns a JSON object.
+* @param {string} text - Input text to parse
+* @param {string} [key='questions'] - Tag name to look for
+* @category Generate
+* @returns {Object[]} Array of objects containing cleaned content items
+*/
+export declare function extractJSONFromLanguageReply(text: any, key?: any): any;

package/dist/prompts/index.d.ts

@@ -0,0 +1,5 @@
+/**
+ * @module agent-toolkit/language-generation/prompts
+ * @description Prompt templates for various AI agent tasks
+ */
+export * from './search-prompts';

package/dist/prompts/meta-search-types.d.ts

@@ -0,0 +1,6 @@
+/**
+ * @module research/search/meta-search-types
+ * @description Shared types for the MetaSearchAgent.
+ */
+/** A `[role, content]` tuple used for few-shot prompt examples. */
+export type FewShotExample = [role: "user" | "assistant", content: string];

package/dist/prompts/search-prompts.d.ts

@@ -0,0 +1,12 @@
+import { FewShotExample } from './meta-search-types';
+export declare const webSearchRetrieverPrompt = "\nYou are an AI question rephraser. You will be given a conversation and a follow-up question,  you will have to rephrase the follow up question so it is a standalone question and can be used by another LLM to search the web for information to answer it.\nIf it is a simple writing task or a greeting (unless the greeting contains a question after it) like Hi, Hello, How are you, etc. than a question then you need to return `not_needed` as the response (This is because the LLM won't need to search the web for finding information on this topic).\nIf the user asks some question from some URL or wants you to summarize a PDF or a webpage (via URL) you need to return the links inside the `links` XML block and the question inside the `question` XML block. If the user wants to you to summarize the webpage or the PDF you need to return `summarize` inside the `question` XML block in place of a question and the link to summarize in the `links` XML block.\nYou must always return the rephrased question inside the `question` XML block, if there are no links in the follow-up question then don't insert a `links` XML block in your response.\n\n**Note**: All user messages are individual entities and should be treated as such do not mix conversations.\n";
+export declare const webSearchRetrieverFewShots: FewShotExample[];
+export declare const webSearchResponsePrompt = "\n    You are QwkSearch, an AI model skilled in web search and crafting detailed, engaging, and well-structured answers. You excel at summarizing web pages and extracting relevant information to create professional, blog-style responses.\n\n    Your task is to provide answers that are:\n    - **Informative and relevant**: Thoroughly address the user's query using the given context.\n    - **Well-structured**: Include clear headings and subheadings, and use a professional tone to present information concisely and logically.\n    - **Engaging and detailed**: Write responses that read like a high-quality blog post, including extra details and relevant insights.\n    - **Cited and credible**: Use inline citations with [number] notation to refer to the context source(s) for each fact or detail included.\n    - **Explanatory and Comprehensive**: Strive to explain the topic in depth, offering detailed analysis, insights, and clarifications wherever applicable.\n\n    ### Formatting Instructions\n    - **Structure**: Use a well-organized format with proper headings (e.g., \"## Example heading 1\" or \"## Example heading 2\"). Present information in paragraphs or concise bullet points where appropriate.\n    - **Tone and Style**: Maintain a neutral, journalistic tone with engaging narrative flow. Write as though you're crafting an in-depth article for a professional audience.\n    - **Markdown Usage**: Format your response with Markdown for clarity. Use headings, subheadings, bold text, and italicized words as needed to enhance readability.\n    - **Length and Depth**: Provide comprehensive coverage of the topic. Avoid superficial responses and strive for depth without unnecessary repetition. Expand on technical or complex topics to make them easier to understand for a general audience.\n    - **No main heading/title**: Start your response directly with the introduction unless asked to provide a specific title.\n    - **Conclusion or Summary**: Include a concluding paragraph that synthesizes the provided information or suggests potential next steps, where appropriate.\n\n    ### Citation Requirements\n    - Cite every single fact, statement, or sentence using [number] notation corresponding to the source from the provided `context`.\n    - Integrate citations naturally at the end of sentences or clauses as appropriate. For example, \"The Eiffel Tower is one of the most visited landmarks in the world[1].\"\n    - Ensure that **every sentence in your response includes at least one citation**, even when information is inferred or connected to general knowledge available in the provided context.\n    - Use multiple sources for a single detail if applicable, such as, \"Paris is a cultural hub, attracting millions of visitors annually[1][2].\"\n    - Always prioritize credibility and accuracy by linking all statements back to their respective context sources.\n    - Avoid citing unsupported assumptions or personal interpretations; if no source supports a statement, clearly indicate the limitation.\n\n    ### Special Instructions\n    - If the query involves technical, historical, or complex topics, provide detailed background and explanatory sections to ensure clarity.\n    - If the user provides vague input or if relevant information is missing, explain what additional details might help refine the search.\n    - If no relevant information is found, say: \"Hmm, sorry I could not find any relevant information on this topic. Would you like me to search again or ask something else?\" Be transparent about limitations and suggest alternatives or ways to reframe the query.\n\n    ### User instructions\n    These instructions are shared to you by the user and not by the system. You will have to follow them but give them less priority than the above instructions. If the user has provided specific instructions or preferences, incorporate them into your response while adhering to the overall guidelines.\n    {systemInstructions}\n\n    ### Example Output\n    - Begin with a brief introduction summarizing the event or query topic.\n    - Follow with detailed sections under clear headings, covering all aspects of the query if possible.\n    - Provide explanations or historical context as needed to enhance understanding.\n    - End with a conclusion or overall perspective if relevant.\n\n    <context>\n    {context}\n    </context>\n\n    Current date & time in ISO format (UTC timezone) is: {date}.\n";
+export declare const writingAssistantPrompt = "\nYou are QwkSearch, an AI model who is expert at searching the web and answering user's queries. You are currently set on focus mode 'Writing Assistant', this means you will be helping the user write a response to a given query.\nYou should still use retrieved web context and cite it while helping the user write a strong response.\nYou will be shared a context that can contain information from files user has uploaded to get answers from. You will have to generate answers upon that.\n\nYou have to cite the answer using [number] notation. You must cite the sentences with their relevent context number. You must cite each and every part of the answer so the user can know where the information is coming from.\nPlace these citations at the end of that particular sentence. You can cite the same sentence multiple times if it is relevant to the user's query like [number1][number2].\nHowever you do not need to cite it using the same number. You can use different numbers to cite the same sentence multiple times. The number refers to the number of the search result (passed in the context) used to generate that part of the answer.\n\n### User instructions\nThese instructions are shared to you by the user and not by the system. You will have to follow them but give them less priority than the above instructions. If the user has provided specific instructions or preferences, incorporate them into your response while adhering to the overall guidelines.\n{systemInstructions}\n\n<context>\n{context}\n</context>\n";
+declare const _default: {
+    webSearchResponsePrompt: string;
+    webSearchRetrieverPrompt: string;
+    webSearchRetrieverFewShots: FewShotExample[];
+    writingAssistantPrompt: string;
+};
+export default _default;

package/dist/provider-factory.d.ts

@@ -0,0 +1,11 @@
+import { LanguageModel } from 'ai';
+/**
+ * Instantiates the appropriate Vercel AI SDK language model for the given provider.
+ *
+ * @param provider    - Normalised (lowercase) provider name
+ * @param apiKey      - Provider API key
+ * @param model       - Model ID to use
+ * @param _temperature - Unused here; temperature is passed to generateText at call time
+ * @returns A LanguageModel instance, or `null` for an unrecognised provider
+ */
+export declare function createLLMProvider(provider: string, apiKey: string, model: string, _temperature: number): LanguageModel | null;

package/dist/tools/qwksearch-api-tools.d.ts

@@ -0,0 +1,149 @@
+import { z } from 'zod';
+/**
+ * List of tools available for agent usage, including their schemas and implementation.
+ */
+export declare const AGENT_TOOLS: ({
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        query: z.ZodString;
+        category: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            general: "general";
+            news: "news";
+            videos: "videos";
+            images: "images";
+            science: "science";
+            files: "files";
+            it: "it";
+        }>>>;
+        recency: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            none: "none";
+            day: "day";
+            week: "week";
+            month: "month";
+            year: "year";
+        }>>>;
+        page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        language: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        public: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ query, category, recency, page, language, public: isPublic, timeout, baseURL, apiKey }: {
+        query: any;
+        category?: string;
+        recency?: string;
+        page?: number;
+        language?: string;
+        public?: boolean;
+        timeout?: number;
+        baseURL: any;
+        apiKey: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        url: z.ZodString;
+        images: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        links: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        formatting: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        absoluteURLs: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ url, images, links, formatting, absoluteURLs, timeout, baseURL, apiKey }: {
+        url: any;
+        images?: boolean;
+        links?: boolean;
+        formatting?: boolean;
+        absoluteURLs?: boolean;
+        timeout?: number;
+        baseURL: any;
+        apiKey: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        provider: z.ZodEnum<{
+            groq: "groq";
+            openai: "openai";
+            anthropic: "anthropic";
+            together: "together";
+            xai: "xai";
+            google: "google";
+            perplexity: "perplexity";
+            cloudflare: "cloudflare";
+        }>;
+        key: z.ZodOptional<z.ZodString>;
+        agent: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            question: "question";
+            "summarize-bullets": "summarize-bullets";
+            summarize: "summarize";
+            "suggest-followups": "suggest-followups";
+            "answer-cite-sources": "answer-cite-sources";
+            "query-resolution": "query-resolution";
+            "knowledge-graph-nodes": "knowledge-graph-nodes";
+            "summary-longtext": "summary-longtext";
+        }>>>;
+        model: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        temperature: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        html: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        query: z.ZodOptional<z.ZodString>;
+        chat_history: z.ZodOptional<z.ZodString>;
+        article: z.ZodOptional<z.ZodString>;
+        baseURL: z.ZodOptional<z.ZodString>;
+        apiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ provider, key, agent, model, temperature, html, query, chat_history, article, baseURL, apiKey }: {
+        provider: any;
+        key: any;
+        agent?: string;
+        model?: string;
+        temperature?: number;
+        html?: boolean;
+        query: any;
+        chat_history: any;
+        article: any;
+        baseURL: any;
+        apiKey: any;
+    }) => Promise<string>;
+} | {
+    name: string;
+    description: string;
+    schema: z.ZodObject<{
+        url: z.ZodString;
+        blockImages: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        wait: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        timeout: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
+        waitUntil: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            domcontentloaded: "domcontentloaded";
+            load: "load";
+            networkidle0: "networkidle0";
+            networkidle2: "networkidle2";
+        }>>>;
+        bypassCaptcha: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        sessionId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        format: z.ZodDefault<z.ZodOptional<z.ZodEnum<{
+            html: "html";
+            json: "json";
+        }>>>;
+        scraperUrl: z.ZodOptional<z.ZodString>;
+        scraperApiKey: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>;
+    func: ({ url, blockImages, wait, timeout, waitUntil, bypassCaptcha, sessionId, format, scraperUrl, scraperApiKey }: {
+        url: any;
+        blockImages?: boolean;
+        wait?: number;
+        timeout?: number;
+        waitUntil?: string;
+        bypassCaptcha?: boolean;
+        sessionId?: string;
+        format?: string;
+        scraperUrl: any;
+        scraperApiKey: any;
+    }) => Promise<string>;
+})[];

package/dist/types.d.ts

@@ -0,0 +1,2 @@
+export * from './index.js'
+export {}

package/dist/utils/markdown-to-html.d.ts

@@ -0,0 +1,5 @@
+/**
+ * Convert markdown text to HTML with Highlight.js syntax highlighting.
+ * Unescapes HTML entities like `&` → `&`.
+ */
+export declare function convertMarkdownToHTMLEscaped(markdown: string): Promise<string>;