auspex 0.4.3 → 0.5.0
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/dist/agent/agent.d.ts.map +1 -1
- package/dist/agent/agent.js +12 -0
- package/dist/agent/agent.js.map +1 -1
- package/dist/agent/loop.d.ts.map +1 -1
- package/dist/agent/loop.js +16 -2
- package/dist/agent/loop.js.map +1 -1
- package/dist/config/schema.d.ts +10 -4
- package/dist/config/schema.d.ts.map +1 -1
- package/dist/config/schema.js +2 -0
- package/dist/config/schema.js.map +1 -1
- package/dist/index.d.ts +3 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +2 -0
- package/dist/index.js.map +1 -1
- package/dist/llm/client.d.ts +6 -1
- package/dist/llm/client.d.ts.map +1 -1
- package/dist/llm/client.js +2 -2
- package/dist/llm/client.js.map +1 -1
- package/dist/llm/prompt.d.ts +7 -2
- package/dist/llm/prompt.d.ts.map +1 -1
- package/dist/llm/prompt.js +31 -2
- package/dist/llm/prompt.js.map +1 -1
- package/dist/macro/build.d.ts +4 -0
- package/dist/macro/build.d.ts.map +1 -0
- package/dist/macro/build.js +23 -0
- package/dist/macro/build.js.map +1 -0
- package/dist/macro/index.d.ts +5 -0
- package/dist/macro/index.d.ts.map +1 -0
- package/dist/macro/index.js +5 -0
- package/dist/macro/index.js.map +1 -0
- package/dist/macro/replay.d.ts +26 -0
- package/dist/macro/replay.d.ts.map +1 -0
- package/dist/macro/replay.js +121 -0
- package/dist/macro/replay.js.map +1 -0
- package/dist/macro/schema.d.ts +440 -0
- package/dist/macro/schema.d.ts.map +1 -0
- package/dist/macro/schema.js +24 -0
- package/dist/macro/schema.js.map +1 -0
- package/dist/macro/serialize.d.ts +4 -0
- package/dist/macro/serialize.d.ts.map +1 -0
- package/dist/macro/serialize.js +20 -0
- package/dist/macro/serialize.js.map +1 -0
- package/dist/security/action-validator.d.ts +2 -2
- package/dist/types.d.ts +9 -0
- package/dist/types.d.ts.map +1 -1
- package/package.json +2 -1
- package/readme.md +55 -0
|
@@ -24,12 +24,12 @@ export declare const actionSchema: z.ZodDiscriminatedUnion<"type", [z.ZodObject<
|
|
|
24
24
|
text: z.ZodString;
|
|
25
25
|
}, "strip", z.ZodTypeAny, {
|
|
26
26
|
type: "type";
|
|
27
|
-
text: string;
|
|
28
27
|
selector: string;
|
|
28
|
+
text: string;
|
|
29
29
|
}, {
|
|
30
30
|
type: "type";
|
|
31
|
-
text: string;
|
|
32
31
|
selector: string;
|
|
32
|
+
text: string;
|
|
33
33
|
}>, z.ZodObject<{
|
|
34
34
|
type: z.ZodLiteral<"select">;
|
|
35
35
|
selector: z.ZodEffects<z.ZodString, string, string>;
|
package/dist/types.d.ts
CHANGED
|
@@ -1,4 +1,5 @@
|
|
|
1
1
|
import type { ZodType } from "zod";
|
|
2
|
+
import type { AuspexMacro } from "./macro/schema.js";
|
|
2
3
|
export type AgentAction = {
|
|
3
4
|
type: "search";
|
|
4
5
|
query: string;
|
|
@@ -33,6 +34,10 @@ export type AgentAction = {
|
|
|
33
34
|
type: "done";
|
|
34
35
|
result: string;
|
|
35
36
|
};
|
|
37
|
+
/** Browser/API steps that can be replayed (excludes terminal `done`). */
|
|
38
|
+
export type ReplayableAction = Exclude<AgentAction, {
|
|
39
|
+
type: "done";
|
|
40
|
+
}>;
|
|
36
41
|
export interface ProxyConfig {
|
|
37
42
|
/** Proxy server URL (e.g. "http://proxy:8080" or "socks5://proxy:1080") */
|
|
38
43
|
server: string;
|
|
@@ -102,6 +107,8 @@ export interface RunOptions {
|
|
|
102
107
|
signal?: AbortSignal;
|
|
103
108
|
/** Zod schema for structured data extraction. When provided, the agent returns validated, typed data. */
|
|
104
109
|
schema?: ZodType;
|
|
110
|
+
/** When false, successful runs omit `macro` on the result. Default: true */
|
|
111
|
+
includeMacro?: boolean;
|
|
105
112
|
/** Override vision auto-fallback setting for this run */
|
|
106
113
|
vision?: boolean;
|
|
107
114
|
/**
|
|
@@ -141,6 +148,8 @@ export interface AgentResult {
|
|
|
141
148
|
usage: LLMUsage;
|
|
142
149
|
memory: MemoryUsage;
|
|
143
150
|
error?: string;
|
|
151
|
+
/** Canonical replay recipe when `status === "done"` and `includeMacro` is not false */
|
|
152
|
+
macro?: AuspexMacro;
|
|
144
153
|
}
|
|
145
154
|
export interface SearchResult {
|
|
146
155
|
title: string;
|
package/dist/types.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,KAAK,CAAC;
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}
|
package/package.json
CHANGED
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "auspex",
|
|
3
|
-
"version": "0.
|
|
3
|
+
"version": "0.5.0",
|
|
4
4
|
"description": "AI-powered browser agent with tiered scraping — HTTP/Cheerio first, Playwright as fallback",
|
|
5
5
|
"type": "module",
|
|
6
6
|
"main": "./dist/index.js",
|
|
@@ -21,6 +21,7 @@
|
|
|
21
21
|
"example": "tsx examples/basic.ts",
|
|
22
22
|
"example:websearch": "tsx examples/websearch.ts",
|
|
23
23
|
"example:scraper": "tsx examples/scraper.ts",
|
|
24
|
+
"example:macro": "tsx examples/macro.ts",
|
|
24
25
|
"install:browser": "playwright install chromium",
|
|
25
26
|
"test": "vitest run",
|
|
26
27
|
"test:watch": "vitest"
|
package/readme.md
CHANGED
|
@@ -15,6 +15,7 @@ Além disso, é compatível com Web Search através de SearXNG
|
|
|
15
15
|
- [AgentConfig — Configuracao completa](#agentconfig--configuracao-completa)
|
|
16
16
|
- [RunOptions](#runoptions)
|
|
17
17
|
- [AgentResult — Retorno da execucao](#agentresult--retorno-da-execucao)
|
|
18
|
+
- [Macro e replay](#macro-e-replay)
|
|
18
19
|
- [Relatorio de Execucao](#relatorio-de-execucao)
|
|
19
20
|
- [Parametros da LLM](#parametros-da-llm)
|
|
20
21
|
- [Providers de LLM compativeis](#providers-de-llm-compativeis)
|
|
@@ -237,6 +238,7 @@ Opcoes passadas para `agent.run(options)`:
|
|
|
237
238
|
| `actionDelayMs` | `number` | Nao | Override de actionDelayMs para este run |
|
|
238
239
|
| `signal` | `AbortSignal` | Nao | AbortSignal para cancelar o run |
|
|
239
240
|
| `schema` | `ZodType<T>` | Nao | Schema Zod: retorno tipado em `data` (T \| null) |
|
|
241
|
+
| `includeMacro` | `boolean` | Nao | Se `false`, omite `macro` no resultado em runs com sucesso. Default: `true` |
|
|
240
242
|
| `vision` | `boolean` | Nao | Override do fallback com screenshot |
|
|
241
243
|
| `searxngUrl` | `string` | Nao | Override do SearXNG **neste run** (sobrescreve `AgentConfig` / `SEARXNG_URL`) |
|
|
242
244
|
|
|
@@ -275,6 +277,7 @@ interface AgentResult {
|
|
|
275
277
|
usage: LLMUsage; // consumo de tokens da LLM
|
|
276
278
|
memory: MemoryUsage; // consumo de memoria
|
|
277
279
|
error?: string; // mensagem de erro (se houver)
|
|
280
|
+
macro?: AuspexMacro; // receita JSON para replay (so em status "done", se includeMacro nao for false)
|
|
278
281
|
}
|
|
279
282
|
```
|
|
280
283
|
|
|
@@ -329,6 +332,46 @@ interface MemoryUsage {
|
|
|
329
332
|
|
|
330
333
|
---
|
|
331
334
|
|
|
335
|
+
## Macro e replay
|
|
336
|
+
|
|
337
|
+
Em runs com **sucesso** (`status === "done"`), o resultado pode incluir `macro`: um JSON canónico com `version`, `startUrl`, `sourceTier`, `steps` (ações sem o terminal `done`) e opcionalmente `capturedResult` (texto do `done` original). No tier **http** com sucesso imediato, `steps` fica vazio — o replay só repete a navegação inicial.
|
|
338
|
+
|
|
339
|
+
Para **serializar** (por exemplo para gravar em ficheiro ou base de dados):
|
|
340
|
+
|
|
341
|
+
```typescript
|
|
342
|
+
import { macroToJsonString, parseMacroJson } from "auspex";
|
|
343
|
+
|
|
344
|
+
const json = macroToJsonString(result.macro!);
|
|
345
|
+
const macro = parseMacroJson(json);
|
|
346
|
+
```
|
|
347
|
+
|
|
348
|
+
Para **reexecutar** sem montar browser à mão, use **`replayMacroWithBrowser(macro, options)`**: faz `launchStealthBrowser`, contexto alinhado ao agent (UA, viewport, locale, stealth init), `replayMacro`, e fecha tudo. Suporta `proxy`, `cookies`, `extraHTTPHeaders`, `browserLaunchOptions` (ex.: `{ headless: false }`).
|
|
349
|
+
|
|
350
|
+
```typescript
|
|
351
|
+
import { replayMacroWithBrowser } from "auspex";
|
|
352
|
+
|
|
353
|
+
const out = await replayMacroWithBrowser(macro, {
|
|
354
|
+
actionDelayMs: 500,
|
|
355
|
+
gotoTimeoutMs: 15_000,
|
|
356
|
+
searxngClient, // obrigatorio se houver passos search
|
|
357
|
+
});
|
|
358
|
+
// out.status === "ok" | "error"
|
|
359
|
+
```
|
|
360
|
+
|
|
361
|
+
Se já tiver uma **`Page`** (mesmo browser que o agent ou outro fluxo), use `replayMacro(page, macro, options)` diretamente. Respeite `allowedDomains` / `blockedDomains` como no agent. Se `steps` contiver `search`, passe `searxngClient` (a chamada à API é repetida; o resultado não é injetado na página — o mesmo comportamento lateral que no agente).
|
|
362
|
+
|
|
363
|
+
Fidelidade **best-effort**: seletores e timing podem falhar se o site mudar. Passos `search` no replay não alteram o DOM.
|
|
364
|
+
|
|
365
|
+
Com `LLM_API_KEY` no `.env`:
|
|
366
|
+
|
|
367
|
+
```bash
|
|
368
|
+
npm run example:macro
|
|
369
|
+
```
|
|
370
|
+
|
|
371
|
+
Veja [`examples/macro.ts`](examples/macro.ts) — um `run` que grava a macro e em seguida executa `replayMacroWithBrowser` num browser novo.
|
|
372
|
+
|
|
373
|
+
---
|
|
374
|
+
|
|
332
375
|
## Relatorio de Execucao
|
|
333
376
|
|
|
334
377
|
Toda execucao gera automaticamente um relatorio descritivo em `result.report`. O relatorio inclui URL, prompt, metodo usado, status, duracao, tokens, memoria e passo a passo humanizado.
|
|
@@ -1054,6 +1097,7 @@ import {
|
|
|
1054
1097
|
type ProxyConfig,
|
|
1055
1098
|
type CookieParam,
|
|
1056
1099
|
type AuspexEvents,
|
|
1100
|
+
type ReplayableAction,
|
|
1057
1101
|
type BrowserPoolOptions,
|
|
1058
1102
|
UrlValidationError,
|
|
1059
1103
|
ActionValidationError,
|
|
@@ -1061,6 +1105,17 @@ import {
|
|
|
1061
1105
|
type SearchResult,
|
|
1062
1106
|
type SearXNGResponse,
|
|
1063
1107
|
type SearXNGClientOptions,
|
|
1108
|
+
buildMacro,
|
|
1109
|
+
macroToJsonString,
|
|
1110
|
+
parseMacroJson,
|
|
1111
|
+
replayMacro,
|
|
1112
|
+
replayMacroWithBrowser,
|
|
1113
|
+
MacroParseError,
|
|
1114
|
+
type AuspexMacro,
|
|
1115
|
+
type MacroReplayOptions,
|
|
1116
|
+
type MacroReplayLaunchOptions,
|
|
1117
|
+
type MacroReplayResult,
|
|
1118
|
+
type MacroReplayStatus,
|
|
1064
1119
|
} from "auspex";
|
|
1065
1120
|
```
|
|
1066
1121
|
|