qwksearch-api-client 0.0.27 → 0.0.28
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/README.md +322 -322
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,322 +1,322 @@
|
|
|
1
|
-
<p align="center">
|
|
2
|
-
<img src="https://i.imgur.com/DqnjYfC.png" alt="QwkSearch Logo" width="200"/>
|
|
3
|
-
</p>
|
|
4
|
-
|
|
5
|
-
<p align="center">
|
|
6
|
-
<strong>Search, extract, vectorize and outline a topic base with AI Research Agent</strong>
|
|
7
|
-
</p>
|
|
8
|
-
|
|
9
|
-
<p align="center">
|
|
10
|
-
<a href="https://qwksearch.com">Demo</a> •
|
|
11
|
-
<a href="https://airesearch.js.org">Documentation</a> •
|
|
12
|
-
<a href="https://github.com/vtempest/ai-research-agent">GitHub</a>
|
|
13
|
-
</p>
|
|
14
|
-
|
|
15
|
-
## Overview
|
|
16
|
-
|
|
17
|
-
QwkSearch API provides three core services for AI-powered research and content analysis:
|
|
18
|
-
|
|
19
|
-
1. **Content Extraction** - Extract structured content and citations from any URL
|
|
20
|
-
2. **Language Generation** - Generate AI responses using multiple language model providers
|
|
21
|
-
3. **Web Search** - Search the web using metasearch engine across 100+ sources
|
|
22
|
-
|
|
23
|
-
|
|
24
|
-
|
|
25
|
-
## Complete Example: Research Pipeline
|
|
26
|
-
|
|
27
|
-
Combine all three endpoints to create a complete research pipeline:
|
|
28
|
-
|
|
29
|
-
```javascript
|
|
30
|
-
import * as qwk from 'qwksearch-api-client';
|
|
31
|
-
|
|
32
|
-
async function researchTopic(topic) {
|
|
33
|
-
// 1. Search for relevant articles
|
|
34
|
-
const searchResults = await qwk.searchWeb({
|
|
35
|
-
query: {
|
|
36
|
-
q: topic,
|
|
37
|
-
cat: 'science',
|
|
38
|
-
recency: 'month'
|
|
39
|
-
}
|
|
40
|
-
});
|
|
41
|
-
|
|
42
|
-
console.log(`Found ${searchResults.results.length} results`);
|
|
43
|
-
|
|
44
|
-
// 2. Extract content from top 3 results
|
|
45
|
-
const articles = await Promise.all(
|
|
46
|
-
searchResults.results.slice(0, 3).map(async (result) => {
|
|
47
|
-
const content = await qwk.extractContent({
|
|
48
|
-
query: {
|
|
49
|
-
url: result.url
|
|
50
|
-
}
|
|
51
|
-
});
|
|
52
|
-
return content;
|
|
53
|
-
})
|
|
54
|
-
);
|
|
55
|
-
|
|
56
|
-
// 3. Generate summary of all articles
|
|
57
|
-
const combinedText = articles
|
|
58
|
-
.map(a => `${a.title}\n\n${a.html}`)
|
|
59
|
-
.join('\n\n---\n\n');
|
|
60
|
-
|
|
61
|
-
const summary = await qwk.writeLanguage({
|
|
62
|
-
body: {
|
|
63
|
-
provider: 'groq',
|
|
64
|
-
key: process.env.GROQ_API_KEY,
|
|
65
|
-
agent: 'summarize-bullets',
|
|
66
|
-
article: combinedText
|
|
67
|
-
}
|
|
68
|
-
});
|
|
69
|
-
|
|
70
|
-
return {
|
|
71
|
-
searchResults: searchResults.results,
|
|
72
|
-
articles,
|
|
73
|
-
summary: summary.content
|
|
74
|
-
};
|
|
75
|
-
}
|
|
76
|
-
|
|
77
|
-
// Run the research pipeline
|
|
78
|
-
researchTopic('quantum computing applications')
|
|
79
|
-
.then(results => {
|
|
80
|
-
console.log('Research Summary:');
|
|
81
|
-
console.log(results.summary);
|
|
82
|
-
});
|
|
83
|
-
```
|
|
84
|
-
|
|
85
|
-
---
|
|
86
|
-
|
|
87
|
-
|
|
88
|
-
## API Endpoints
|
|
89
|
-
|
|
90
|
-
### 1. Extract Content (`/extract`)
|
|
91
|
-
|
|
92
|
-
Extract structured content, citations, and metadata from any URL including articles, PDFs, and YouTube videos.
|
|
93
|
-
|
|
94
|
-
#### Features
|
|
95
|
-
|
|
96
|
-
- **Main Content Detection**: Combines Mozilla Readability and Postlight Mercury algorithms with 100+ custom adapters
|
|
97
|
-
- **HTML Standardization**: Transforms complex HTML into simplified reading-mode format
|
|
98
|
-
- **YouTube Transcripts**: Retrieves complete video transcripts with timestamps
|
|
99
|
-
- **PDF Processing**: Extracts formatted text and infers heading hierarchy
|
|
100
|
-
- **Citation Extraction**: Identifies author names, publication dates, sources, and titles
|
|
101
|
-
- **Author Formatting**: Validates against 90,000+ name database for proper citation formatting
|
|
102
|
-
|
|
103
|
-
#### Request
|
|
104
|
-
|
|
105
|
-
```http
|
|
106
|
-
GET /extract?url={url}&images={boolean}&links={boolean}
|
|
107
|
-
```
|
|
108
|
-
|
|
109
|
-
**Parameters:**
|
|
110
|
-
|
|
111
|
-
| Parameter | Type | Required | Default | Description |
|
|
112
|
-
|-----------|------|----------|---------|-------------|
|
|
113
|
-
| `url` | string (uri) | Yes | - | URL to extract content from |
|
|
114
|
-
| `images` | boolean | No | true | Include images in output |
|
|
115
|
-
| `links` | boolean | No | true | Include hyperlinks in output |
|
|
116
|
-
| `formatting` | boolean | No | true | Preserve text formatting |
|
|
117
|
-
| `absoluteURLs` | boolean | No | true | Convert relative URLs to absolute |
|
|
118
|
-
| `timeout` | integer | No | 5 | HTTP request timeout (1-30 seconds) |
|
|
119
|
-
|
|
120
|
-
|
|
121
|
-
### 2. Generate Language (`/agents`)
|
|
122
|
-
|
|
123
|
-
Generate AI responses using various language model providers with pre-built agent templates.
|
|
124
|
-
|
|
125
|
-
#### Language Intelligence Providers (LIPs)
|
|
126
|
-
|
|
127
|
-
| Provider | Model Families | Cost (1M Output) | Valuation |
|
|
128
|
-
|----------|----------------|------------------|-----------|
|
|
129
|
-
| **Groq** | Llama, DeepSeek, Gemini, Mistral | $0.79 | $2.8B |
|
|
130
|
-
| **Ollama** | llama, mistral, mixtral, gemma, qwen, deepseek | $0 (local) | - |
|
|
131
|
-
| **OpenAI** | o1, o4, gpt-4, gpt-4-turbo, gpt-4-omni | $8.00 | $300B |
|
|
132
|
-
| **Anthropic** | Claude Sonnet, Opus, Haiku | $15.00 | $61.5B |
|
|
133
|
-
| **TogetherAI** | Llama, Mistral, Qwen, DeepSeek | $0.90 | $3.3B |
|
|
134
|
-
| **Perplexity** | Sonar, Sonar Deep Research | $15.00 | $18B |
|
|
135
|
-
| **XAI** | Grok, Grok Vision | $15.00 | $80B |
|
|
136
|
-
| **Google** | Gemini | $10.00 | - |
|
|
137
|
-
| **Cloudflare** | Llama, Gemma, Mistral, Phi, Qwen | $2.25 | $62.3B |
|
|
138
|
-
|
|
139
|
-
#### Agent Templates
|
|
140
|
-
|
|
141
|
-
| Agent | Context Variables | Description |
|
|
142
|
-
|-------|------------------|-------------|
|
|
143
|
-
| `question` | query, chat_history | Answer questions with conversation context |
|
|
144
|
-
| `summarize-bullets` | article | Create bullet-point summaries |
|
|
145
|
-
| `summarize` | article | Generate narrative summaries |
|
|
146
|
-
| `suggest-followups` | chat_history, article | Suggest follow-up questions (returns string[]) |
|
|
147
|
-
| `answer-cite-sources` | context, chat_history, query | Answer with source citations |
|
|
148
|
-
| `query-resolution` | chat_history, query | Resolve ambiguous queries |
|
|
149
|
-
| `knowledge-graph-nodes` | query, article | Extract knowledge graph nodes |
|
|
150
|
-
| `summary-longtext` | summaries | Summarize multiple summaries |
|
|
151
|
-
|
|
152
|
-
#### Request
|
|
153
|
-
|
|
154
|
-
```http
|
|
155
|
-
POST /agents
|
|
156
|
-
Content-Type: application/json
|
|
157
|
-
|
|
158
|
-
{
|
|
159
|
-
"provider": "groq",
|
|
160
|
-
"key": "your-api-key",
|
|
161
|
-
"agent": "question",
|
|
162
|
-
"model": "llama-3.3-70b-versatile",
|
|
163
|
-
"query": "What is quantum computing?",
|
|
164
|
-
"temperature": 1.0,
|
|
165
|
-
"html": true
|
|
166
|
-
}
|
|
167
|
-
```
|
|
168
|
-
|
|
169
|
-
**Body Parameters:**
|
|
170
|
-
|
|
171
|
-
| Parameter | Type | Required | Default | Description |
|
|
172
|
-
|-----------|------|----------|---------|-------------|
|
|
173
|
-
| `provider` | string | Yes | - | LIP provider: groq, openai, anthropic, together, xai, google, perplexity, ollama, cloudflare |
|
|
174
|
-
| `key` | string | Yes | - | API key for the provider |
|
|
175
|
-
| `agent` | string | No | question | Agent template name |
|
|
176
|
-
| `model` | string | No | llama-4-maverick-17b | Model name for the provider |
|
|
177
|
-
| `html` | boolean | No | true | Format response as HTML (true) or Markdown (false) |
|
|
178
|
-
| `temperature` | number | No | 1.0 | 0-1: deterministic, 1-2: creative |
|
|
179
|
-
| `query` | string | No | - | Query text for certain agents |
|
|
180
|
-
| `chat_history` | string | No | - | Conversation history for certain agents |
|
|
181
|
-
| `article` | string | No | - | Article text for summarization agents |
|
|
182
|
-
|
|
183
|
-
#### Response
|
|
184
|
-
|
|
185
|
-
**200 OK**
|
|
186
|
-
|
|
187
|
-
```json
|
|
188
|
-
{
|
|
189
|
-
"content": "Generated response in HTML or Markdown format",
|
|
190
|
-
"extract": {
|
|
191
|
-
"structured": "data"
|
|
192
|
-
}
|
|
193
|
-
}
|
|
194
|
-
```
|
|
195
|
-
|
|
196
|
-
#### Example Usage
|
|
197
|
-
|
|
198
|
-
```javascript
|
|
199
|
-
import * as qwk from 'qwksearch-api-client';
|
|
200
|
-
|
|
201
|
-
// Question answering
|
|
202
|
-
const response = await qwk.writeLanguage({
|
|
203
|
-
body: {
|
|
204
|
-
provider: 'groq',
|
|
205
|
-
key: process.env.GROQ_API_KEY,
|
|
206
|
-
agent: 'question',
|
|
207
|
-
query: 'Explain neural networks',
|
|
208
|
-
temperature: 0.7
|
|
209
|
-
}
|
|
210
|
-
});
|
|
211
|
-
|
|
212
|
-
const { content } = response;
|
|
213
|
-
console.log(content);
|
|
214
|
-
|
|
215
|
-
// Summarize article
|
|
216
|
-
const summary = await qwk.writeLanguage({
|
|
217
|
-
body: {
|
|
218
|
-
provider: 'anthropic',
|
|
219
|
-
key: process.env.ANTHROPIC_API_KEY,
|
|
220
|
-
agent: 'summarize-bullets',
|
|
221
|
-
article: articleText,
|
|
222
|
-
html: false // Get Markdown
|
|
223
|
-
}
|
|
224
|
-
});
|
|
225
|
-
|
|
226
|
-
// Answer with citations
|
|
227
|
-
const answer = await qwk.writeLanguage({
|
|
228
|
-
body: {
|
|
229
|
-
provider: 'openai',
|
|
230
|
-
key: process.env.OPENAI_API_KEY,
|
|
231
|
-
agent: 'answer-cite-sources',
|
|
232
|
-
query: 'What causes climate change?',
|
|
233
|
-
context: 'Scientific articles about greenhouse gases...',
|
|
234
|
-
temperature: 0.5
|
|
235
|
-
}
|
|
236
|
-
});
|
|
237
|
-
console.log(answer.content);
|
|
238
|
-
```
|
|
239
|
-
|
|
240
|
-
---
|
|
241
|
-
|
|
242
|
-
### 3. Search Web (`/search`)
|
|
243
|
-
|
|
244
|
-
Search the web using metasearch engine aggregating 100+ search sources.
|
|
245
|
-
|
|
246
|
-
#### Features
|
|
247
|
-
|
|
248
|
-
- **Privacy-Focused**: No tracking or personal data collection
|
|
249
|
-
- **Multiple Categories**: General, news, videos, images, science, files, IT
|
|
250
|
-
- **Recency Filters**: Filter by day, week, month, year
|
|
251
|
-
- **Multi-Language**: Support for various languages
|
|
252
|
-
- **Diverse Sources**: Aggregates from 100+ search engines
|
|
253
|
-
- Search index exceeds 100,000,000 GB covering 130 trillion pages
|
|
254
|
-
- Uses 200+ ranking factors including keywords, backlinks, page speed
|
|
255
|
-
|
|
256
|
-
#### Request
|
|
257
|
-
|
|
258
|
-
```http
|
|
259
|
-
GET /search?q={query}&cat={category}&recency={filter}&lang={language}
|
|
260
|
-
```
|
|
261
|
-
|
|
262
|
-
**Parameters:**
|
|
263
|
-
|
|
264
|
-
| Parameter | Type | Required | Default | Description |
|
|
265
|
-
|-----------|------|----------|---------|-------------|
|
|
266
|
-
| `q` | string | Yes | - | Search query string |
|
|
267
|
-
| `cat` | string | No | general | Category: general, news, videos, images, science, files, it |
|
|
268
|
-
| `recency` | string | No | all | Time filter: all, day, week, month, year |
|
|
269
|
-
| `safesearch` | boolean | No | false | Block adult content |
|
|
270
|
-
| `public` | boolean | No | false | Use public server instances |
|
|
271
|
-
| `page` | integer | No | 1 | Pagination for results |
|
|
272
|
-
| `lang` | string | No | en-US | Language code |
|
|
273
|
-
|
|
274
|
-
#### Response
|
|
275
|
-
|
|
276
|
-
**200 OK**
|
|
277
|
-
|
|
278
|
-
```json
|
|
279
|
-
{
|
|
280
|
-
"results": [
|
|
281
|
-
{
|
|
282
|
-
"title": "Search result title",
|
|
283
|
-
"url": "https://example.com/page",
|
|
284
|
-
"snippet": "Text snippet around the query...",
|
|
285
|
-
"domain": "example.com",
|
|
286
|
-
"favicon": "https://example.com/favicon.ico",
|
|
287
|
-
"path": "/page",
|
|
288
|
-
"engines": "google,bing"
|
|
289
|
-
}
|
|
290
|
-
]
|
|
291
|
-
}
|
|
292
|
-
```
|
|
293
|
-
|
|
294
|
-
## Installation
|
|
295
|
-
|
|
296
|
-
### NPM Package
|
|
297
|
-
|
|
298
|
-
```bash
|
|
299
|
-
npm install qwksearch-api-client
|
|
300
|
-
```
|
|
301
|
-
|
|
302
|
-
---
|
|
303
|
-
|
|
304
|
-
|
|
305
|
-
|
|
306
|
-
## Links
|
|
307
|
-
|
|
308
|
-
- **Documentation**: [airesearch.js.org](https://airesearch.js.org/)
|
|
309
|
-
- **Demo**: [qwksearch.com](https://qwksearch.com/)
|
|
310
|
-
- **GitHub**: [github.com/vtempest/ai-research-agent](https://github.com/vtempest/ai-research-agent)
|
|
311
|
-
- **OpenAPI Spec**: [View Full Specification](./qwksearch-openapi.yml)
|
|
312
|
-
|
|
313
|
-
- [LLM Training Example](https://github.com/vtempest/ai-research-agent/blob/master/packages/neural-net/src/train/predict-next-word.js)
|
|
314
|
-
- [LangChain ReactAgent Tools](https://medium.com/@terrycho/how-langchain-agent-works-internally-trace-by-using-langsmith-df23766e7fb4)
|
|
315
|
-
- [Hugging Face Tutorials](https://huggingface.co/learn)
|
|
316
|
-
- [OpenAI Cookbook](https://cookbook.openai.com)
|
|
317
|
-
- [Transformer Overview](https://jalammar.github.io/illustrated-transformer/)
|
|
318
|
-
- [Building Transformer Guide](https://www.datacamp.com/tutorial/building-a-transformer-with-py-torch)
|
|
319
|
-
- [PyTorch Overview](https://www.learnpytorch.io/pytorch_cheatsheet/)
|
|
320
|
-
- [SearXNG Overview](https://medium.com/@elmo92/search-in-peace-with--an-alternative-search-engine-that-keeps-your-searches-private-accd8cddd6fc)
|
|
321
|
-
- [Evaluating Large Language Models in Scientific Discovery](https://arxiv.org/pdf/2512.15567)
|
|
322
|
-
---
|
|
1
|
+
<p align="center">
|
|
2
|
+
<img src="https://i.imgur.com/DqnjYfC.png" alt="QwkSearch Logo" width="200"/>
|
|
3
|
+
</p>
|
|
4
|
+
|
|
5
|
+
<p align="center">
|
|
6
|
+
<strong>Search, extract, vectorize and outline a topic base with AI Research Agent</strong>
|
|
7
|
+
</p>
|
|
8
|
+
|
|
9
|
+
<p align="center">
|
|
10
|
+
<a href="https://qwksearch.com">Demo</a> •
|
|
11
|
+
<a href="https://airesearch.js.org">Documentation</a> •
|
|
12
|
+
<a href="https://github.com/vtempest/ai-research-agent">GitHub</a>
|
|
13
|
+
</p>
|
|
14
|
+
|
|
15
|
+
## Overview
|
|
16
|
+
|
|
17
|
+
QwkSearch API provides three core services for AI-powered research and content analysis:
|
|
18
|
+
|
|
19
|
+
1. **Content Extraction** - Extract structured content and citations from any URL
|
|
20
|
+
2. **Language Generation** - Generate AI responses using multiple language model providers
|
|
21
|
+
3. **Web Search** - Search the web using metasearch engine across 100+ sources
|
|
22
|
+
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
## Complete Example: Research Pipeline
|
|
26
|
+
|
|
27
|
+
Combine all three endpoints to create a complete research pipeline:
|
|
28
|
+
|
|
29
|
+
```javascript
|
|
30
|
+
import * as qwk from 'qwksearch-api-client';
|
|
31
|
+
|
|
32
|
+
async function researchTopic(topic) {
|
|
33
|
+
// 1. Search for relevant articles
|
|
34
|
+
const searchResults = await qwk.searchWeb({
|
|
35
|
+
query: {
|
|
36
|
+
q: topic,
|
|
37
|
+
cat: 'science',
|
|
38
|
+
recency: 'month'
|
|
39
|
+
}
|
|
40
|
+
});
|
|
41
|
+
|
|
42
|
+
console.log(`Found ${searchResults.results.length} results`);
|
|
43
|
+
|
|
44
|
+
// 2. Extract content from top 3 results
|
|
45
|
+
const articles = await Promise.all(
|
|
46
|
+
searchResults.results.slice(0, 3).map(async (result) => {
|
|
47
|
+
const content = await qwk.extractContent({
|
|
48
|
+
query: {
|
|
49
|
+
url: result.url
|
|
50
|
+
}
|
|
51
|
+
});
|
|
52
|
+
return content;
|
|
53
|
+
})
|
|
54
|
+
);
|
|
55
|
+
|
|
56
|
+
// 3. Generate summary of all articles
|
|
57
|
+
const combinedText = articles
|
|
58
|
+
.map(a => `${a.title}\n\n${a.html}`)
|
|
59
|
+
.join('\n\n---\n\n');
|
|
60
|
+
|
|
61
|
+
const summary = await qwk.writeLanguage({
|
|
62
|
+
body: {
|
|
63
|
+
provider: 'groq',
|
|
64
|
+
key: process.env.GROQ_API_KEY,
|
|
65
|
+
agent: 'summarize-bullets',
|
|
66
|
+
article: combinedText
|
|
67
|
+
}
|
|
68
|
+
});
|
|
69
|
+
|
|
70
|
+
return {
|
|
71
|
+
searchResults: searchResults.results,
|
|
72
|
+
articles,
|
|
73
|
+
summary: summary.content
|
|
74
|
+
};
|
|
75
|
+
}
|
|
76
|
+
|
|
77
|
+
// Run the research pipeline
|
|
78
|
+
researchTopic('quantum computing applications')
|
|
79
|
+
.then(results => {
|
|
80
|
+
console.log('Research Summary:');
|
|
81
|
+
console.log(results.summary);
|
|
82
|
+
});
|
|
83
|
+
```
|
|
84
|
+
|
|
85
|
+
---
|
|
86
|
+
|
|
87
|
+
|
|
88
|
+
## API Endpoints
|
|
89
|
+
|
|
90
|
+
### 1. Extract Content (`/extract`)
|
|
91
|
+
|
|
92
|
+
Extract structured content, citations, and metadata from any URL including articles, PDFs, and YouTube videos.
|
|
93
|
+
|
|
94
|
+
#### Features
|
|
95
|
+
|
|
96
|
+
- **Main Content Detection**: Combines Mozilla Readability and Postlight Mercury algorithms with 100+ custom adapters
|
|
97
|
+
- **HTML Standardization**: Transforms complex HTML into simplified reading-mode format
|
|
98
|
+
- **YouTube Transcripts**: Retrieves complete video transcripts with timestamps
|
|
99
|
+
- **PDF Processing**: Extracts formatted text and infers heading hierarchy
|
|
100
|
+
- **Citation Extraction**: Identifies author names, publication dates, sources, and titles
|
|
101
|
+
- **Author Formatting**: Validates against 90,000+ name database for proper citation formatting
|
|
102
|
+
|
|
103
|
+
#### Request
|
|
104
|
+
|
|
105
|
+
```http
|
|
106
|
+
GET /extract?url={url}&images={boolean}&links={boolean}
|
|
107
|
+
```
|
|
108
|
+
|
|
109
|
+
**Parameters:**
|
|
110
|
+
|
|
111
|
+
| Parameter | Type | Required | Default | Description |
|
|
112
|
+
|-----------|------|----------|---------|-------------|
|
|
113
|
+
| `url` | string (uri) | Yes | - | URL to extract content from |
|
|
114
|
+
| `images` | boolean | No | true | Include images in output |
|
|
115
|
+
| `links` | boolean | No | true | Include hyperlinks in output |
|
|
116
|
+
| `formatting` | boolean | No | true | Preserve text formatting |
|
|
117
|
+
| `absoluteURLs` | boolean | No | true | Convert relative URLs to absolute |
|
|
118
|
+
| `timeout` | integer | No | 5 | HTTP request timeout (1-30 seconds) |
|
|
119
|
+
|
|
120
|
+
|
|
121
|
+
### 2. Generate Language (`/agents`)
|
|
122
|
+
|
|
123
|
+
Generate AI responses using various language model providers with pre-built agent templates.
|
|
124
|
+
|
|
125
|
+
#### Language Intelligence Providers (LIPs)
|
|
126
|
+
|
|
127
|
+
| Provider | Model Families | Cost (1M Output) | Valuation |
|
|
128
|
+
|----------|----------------|------------------|-----------|
|
|
129
|
+
| **Groq** | Llama, DeepSeek, Gemini, Mistral | $0.79 | $2.8B |
|
|
130
|
+
| **Ollama** | llama, mistral, mixtral, gemma, qwen, deepseek | $0 (local) | - |
|
|
131
|
+
| **OpenAI** | o1, o4, gpt-4, gpt-4-turbo, gpt-4-omni | $8.00 | $300B |
|
|
132
|
+
| **Anthropic** | Claude Sonnet, Opus, Haiku | $15.00 | $61.5B |
|
|
133
|
+
| **TogetherAI** | Llama, Mistral, Qwen, DeepSeek | $0.90 | $3.3B |
|
|
134
|
+
| **Perplexity** | Sonar, Sonar Deep Research | $15.00 | $18B |
|
|
135
|
+
| **XAI** | Grok, Grok Vision | $15.00 | $80B |
|
|
136
|
+
| **Google** | Gemini | $10.00 | - |
|
|
137
|
+
| **Cloudflare** | Llama, Gemma, Mistral, Phi, Qwen | $2.25 | $62.3B |
|
|
138
|
+
|
|
139
|
+
#### Agent Templates
|
|
140
|
+
|
|
141
|
+
| Agent | Context Variables | Description |
|
|
142
|
+
|-------|------------------|-------------|
|
|
143
|
+
| `question` | query, chat_history | Answer questions with conversation context |
|
|
144
|
+
| `summarize-bullets` | article | Create bullet-point summaries |
|
|
145
|
+
| `summarize` | article | Generate narrative summaries |
|
|
146
|
+
| `suggest-followups` | chat_history, article | Suggest follow-up questions (returns string[]) |
|
|
147
|
+
| `answer-cite-sources` | context, chat_history, query | Answer with source citations |
|
|
148
|
+
| `query-resolution` | chat_history, query | Resolve ambiguous queries |
|
|
149
|
+
| `knowledge-graph-nodes` | query, article | Extract knowledge graph nodes |
|
|
150
|
+
| `summary-longtext` | summaries | Summarize multiple summaries |
|
|
151
|
+
|
|
152
|
+
#### Request
|
|
153
|
+
|
|
154
|
+
```http
|
|
155
|
+
POST /agents
|
|
156
|
+
Content-Type: application/json
|
|
157
|
+
|
|
158
|
+
{
|
|
159
|
+
"provider": "groq",
|
|
160
|
+
"key": "your-api-key",
|
|
161
|
+
"agent": "question",
|
|
162
|
+
"model": "llama-3.3-70b-versatile",
|
|
163
|
+
"query": "What is quantum computing?",
|
|
164
|
+
"temperature": 1.0,
|
|
165
|
+
"html": true
|
|
166
|
+
}
|
|
167
|
+
```
|
|
168
|
+
|
|
169
|
+
**Body Parameters:**
|
|
170
|
+
|
|
171
|
+
| Parameter | Type | Required | Default | Description |
|
|
172
|
+
|-----------|------|----------|---------|-------------|
|
|
173
|
+
| `provider` | string | Yes | - | LIP provider: groq, openai, anthropic, together, xai, google, perplexity, ollama, cloudflare |
|
|
174
|
+
| `key` | string | Yes | - | API key for the provider |
|
|
175
|
+
| `agent` | string | No | question | Agent template name |
|
|
176
|
+
| `model` | string | No | llama-4-maverick-17b | Model name for the provider |
|
|
177
|
+
| `html` | boolean | No | true | Format response as HTML (true) or Markdown (false) |
|
|
178
|
+
| `temperature` | number | No | 1.0 | 0-1: deterministic, 1-2: creative |
|
|
179
|
+
| `query` | string | No | - | Query text for certain agents |
|
|
180
|
+
| `chat_history` | string | No | - | Conversation history for certain agents |
|
|
181
|
+
| `article` | string | No | - | Article text for summarization agents |
|
|
182
|
+
|
|
183
|
+
#### Response
|
|
184
|
+
|
|
185
|
+
**200 OK**
|
|
186
|
+
|
|
187
|
+
```json
|
|
188
|
+
{
|
|
189
|
+
"content": "Generated response in HTML or Markdown format",
|
|
190
|
+
"extract": {
|
|
191
|
+
"structured": "data"
|
|
192
|
+
}
|
|
193
|
+
}
|
|
194
|
+
```
|
|
195
|
+
|
|
196
|
+
#### Example Usage
|
|
197
|
+
|
|
198
|
+
```javascript
|
|
199
|
+
import * as qwk from 'qwksearch-api-client';
|
|
200
|
+
|
|
201
|
+
// Question answering
|
|
202
|
+
const response = await qwk.writeLanguage({
|
|
203
|
+
body: {
|
|
204
|
+
provider: 'groq',
|
|
205
|
+
key: process.env.GROQ_API_KEY,
|
|
206
|
+
agent: 'question',
|
|
207
|
+
query: 'Explain neural networks',
|
|
208
|
+
temperature: 0.7
|
|
209
|
+
}
|
|
210
|
+
});
|
|
211
|
+
|
|
212
|
+
const { content } = response;
|
|
213
|
+
console.log(content);
|
|
214
|
+
|
|
215
|
+
// Summarize article
|
|
216
|
+
const summary = await qwk.writeLanguage({
|
|
217
|
+
body: {
|
|
218
|
+
provider: 'anthropic',
|
|
219
|
+
key: process.env.ANTHROPIC_API_KEY,
|
|
220
|
+
agent: 'summarize-bullets',
|
|
221
|
+
article: articleText,
|
|
222
|
+
html: false // Get Markdown
|
|
223
|
+
}
|
|
224
|
+
});
|
|
225
|
+
|
|
226
|
+
// Answer with citations
|
|
227
|
+
const answer = await qwk.writeLanguage({
|
|
228
|
+
body: {
|
|
229
|
+
provider: 'openai',
|
|
230
|
+
key: process.env.OPENAI_API_KEY,
|
|
231
|
+
agent: 'answer-cite-sources',
|
|
232
|
+
query: 'What causes climate change?',
|
|
233
|
+
context: 'Scientific articles about greenhouse gases...',
|
|
234
|
+
temperature: 0.5
|
|
235
|
+
}
|
|
236
|
+
});
|
|
237
|
+
console.log(answer.content);
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
---
|
|
241
|
+
|
|
242
|
+
### 3. Search Web (`/search`)
|
|
243
|
+
|
|
244
|
+
Search the web using metasearch engine aggregating 100+ search sources.
|
|
245
|
+
|
|
246
|
+
#### Features
|
|
247
|
+
|
|
248
|
+
- **Privacy-Focused**: No tracking or personal data collection
|
|
249
|
+
- **Multiple Categories**: General, news, videos, images, science, files, IT
|
|
250
|
+
- **Recency Filters**: Filter by day, week, month, year
|
|
251
|
+
- **Multi-Language**: Support for various languages
|
|
252
|
+
- **Diverse Sources**: Aggregates from 100+ search engines
|
|
253
|
+
- Search index exceeds 100,000,000 GB covering 130 trillion pages
|
|
254
|
+
- Uses 200+ ranking factors including keywords, backlinks, page speed
|
|
255
|
+
|
|
256
|
+
#### Request
|
|
257
|
+
|
|
258
|
+
```http
|
|
259
|
+
GET /search?q={query}&cat={category}&recency={filter}&lang={language}
|
|
260
|
+
```
|
|
261
|
+
|
|
262
|
+
**Parameters:**
|
|
263
|
+
|
|
264
|
+
| Parameter | Type | Required | Default | Description |
|
|
265
|
+
|-----------|------|----------|---------|-------------|
|
|
266
|
+
| `q` | string | Yes | - | Search query string |
|
|
267
|
+
| `cat` | string | No | general | Category: general, news, videos, images, science, files, it |
|
|
268
|
+
| `recency` | string | No | all | Time filter: all, day, week, month, year |
|
|
269
|
+
| `safesearch` | boolean | No | false | Block adult content |
|
|
270
|
+
| `public` | boolean | No | false | Use public server instances |
|
|
271
|
+
| `page` | integer | No | 1 | Pagination for results |
|
|
272
|
+
| `lang` | string | No | en-US | Language code |
|
|
273
|
+
|
|
274
|
+
#### Response
|
|
275
|
+
|
|
276
|
+
**200 OK**
|
|
277
|
+
|
|
278
|
+
```json
|
|
279
|
+
{
|
|
280
|
+
"results": [
|
|
281
|
+
{
|
|
282
|
+
"title": "Search result title",
|
|
283
|
+
"url": "https://example.com/page",
|
|
284
|
+
"snippet": "Text snippet around the query...",
|
|
285
|
+
"domain": "example.com",
|
|
286
|
+
"favicon": "https://example.com/favicon.ico",
|
|
287
|
+
"path": "/page",
|
|
288
|
+
"engines": "google,bing"
|
|
289
|
+
}
|
|
290
|
+
]
|
|
291
|
+
}
|
|
292
|
+
```
|
|
293
|
+
|
|
294
|
+
## Installation
|
|
295
|
+
|
|
296
|
+
### NPM Package
|
|
297
|
+
|
|
298
|
+
```bash
|
|
299
|
+
npm install qwksearch-api-client
|
|
300
|
+
```
|
|
301
|
+
|
|
302
|
+
---
|
|
303
|
+
|
|
304
|
+
|
|
305
|
+
|
|
306
|
+
## Links
|
|
307
|
+
|
|
308
|
+
- **Documentation**: [airesearch.js.org](https://airesearch.js.org/)
|
|
309
|
+
- **Demo**: [qwksearch.com](https://qwksearch.com/)
|
|
310
|
+
- **GitHub**: [github.com/vtempest/ai-research-agent](https://github.com/vtempest/ai-research-agent)
|
|
311
|
+
- **OpenAPI Spec**: [View Full Specification](./qwksearch-openapi.yml)
|
|
312
|
+
|
|
313
|
+
- [LLM Training Example](https://github.com/vtempest/ai-research-agent/blob/master/packages/neural-net/src/train/predict-next-word.js)
|
|
314
|
+
- [LangChain ReactAgent Tools](https://medium.com/@terrycho/how-langchain-agent-works-internally-trace-by-using-langsmith-df23766e7fb4)
|
|
315
|
+
- [Hugging Face Tutorials](https://huggingface.co/learn)
|
|
316
|
+
- [OpenAI Cookbook](https://cookbook.openai.com)
|
|
317
|
+
- [Transformer Overview](https://jalammar.github.io/illustrated-transformer/)
|
|
318
|
+
- [Building Transformer Guide](https://www.datacamp.com/tutorial/building-a-transformer-with-py-torch)
|
|
319
|
+
- [PyTorch Overview](https://www.learnpytorch.io/pytorch_cheatsheet/)
|
|
320
|
+
- [SearXNG Overview](https://medium.com/@elmo92/search-in-peace-with--an-alternative-search-engine-that-keeps-your-searches-private-accd8cddd6fc)
|
|
321
|
+
- [Evaluating Large Language Models in Scientific Discovery](https://arxiv.org/pdf/2512.15567)
|
|
322
|
+
---
|