From 92cb3b5dec8cf56d38f8719fbcc901399c572d5f Mon Sep 17 00:00:00 2001 From: wguDataNinja Date: Thu, 21 May 2026 13:25:11 -0400 Subject: [PATCH 1/2] =?UTF-8?q?Add=20AGENTS.md=20=E2=80=94=20purpose,=20la?= =?UTF-8?q?yout,=20commands,=20watchouts?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- AGENTS.md | 62 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 62 insertions(+) create mode 100644 AGENTS.md diff --git a/AGENTS.md b/AGENTS.md new file mode 100644 index 0000000..862dfd1 --- /dev/null +++ b/AGENTS.md @@ -0,0 +1,62 @@ +# AGENTS.md — deep-research + +## Purpose + +Open-source TypeScript library for multi-hop web-based deep research. +Built by JigsawStack as an open alternative to Perplexity / OpenAI Deep Research. +Combines an LLM-driven reasoning engine with web search (JigsawStack API) to +break complex questions into sub-queries, gather evidence, and produce cited +reports. Published as `deep-research` on npm. + +## Status + +Active, maintained. v0.1.4 — Apache 2.0 license. Single `main` branch. +Used as a library dependency; no CLI or web UI. + +## Directory Layout + +``` +src/ + index.ts — DeepResearch class (public API) + process.ts — Research pipeline (plan → search → reason → report) + config/defaults.ts — Default configuration constants + provider/ + aiProvider.ts — Model provider abstraction (OpenAI, Gemini, OpenRouter, etc.) + jigsaw.ts — JigsawStack SDK wrapper + webSearch.ts — Web search provider + prompts/prompts.ts — LLM prompt templates + types/types.ts — TypeScript type definitions + utils/ + logger.ts — Console logging utility + utils.ts — General helpers (URL dedup, number mapping) +examples/ + simple_research.ts + advanced_research.ts +public/ + open_deep_research_diagram.png +.github/workflows/publish.yml — npm publish CI +``` + +## Commands + +| Command | Action | +|-------------------|-------------------------------| +| `npm i deep-research` | Install the library | +| `yarn build` | Build dist/ via pkgroll | +| `yarn lint` | Lint with Biome | +| `yarn format` | Auto-format with Biome | +| `yarn dev` | Run examples/simple_research.ts via tsx | +| `yarn add ` | Add dependency | + +## Watchouts + +- **JigsawStack API key required** — `JIGSAW_API_KEY` is mandatory; the library + won't function without it. Also needs keys for chosen AI providers. +- **No tests** — No test runner or test files in the repo. Quality relies on the + Biome linter and manual example runs. +- **`examples/` change API** — The `examples/simple_research.ts` file was modified + locally but never committed (see git log — the latest commit touches a different + `update/examples` branch). Example code may be out of sync with the published API. +- **.env is gitignored** — Confirmed: `.env`, `.env.*`, `*.env` all in `.gitignore`. + No secret files present in the repo. +- **Node >=18 required** — Package uses ESM (`"type": "module"`). From aac20caca9b76375a6263edc818da51540e1b6c6 Mon Sep 17 00:00:00 2001 From: wguDataNinja Date: Thu, 21 May 2026 13:28:20 -0400 Subject: [PATCH 2/2] fix AGENTS.md watchout #3: correct inaccurate examples claim MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit The previous wording claimed examples/simple_research.ts 'was modified locally but never committed' — this was false. The examples were last updated on the update/examples branch (commit 91af1f2) which was merged to main via PR #38 (commit 33edd18). The v0.1.4 version bump (commit 243996e) happened after those changes, so example code may reference v0.1.3 APIs that differ from the current release. --- AGENTS.md | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index 862dfd1..fa4db24 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -54,9 +54,11 @@ public/ won't function without it. Also needs keys for chosen AI providers. - **No tests** — No test runner or test files in the repo. Quality relies on the Biome linter and manual example runs. -- **`examples/` change API** — The `examples/simple_research.ts` file was modified - locally but never committed (see git log — the latest commit touches a different - `update/examples` branch). Example code may be out of sync with the published API. +- **`examples/` change API** — The examples in `examples/` were last updated on + the `update/examples` branch (commit `91af1f2`, merged to `main` via PR #38 as + commit `33edd18`). The version bump to v0.1.4 (commit `243996e`) happened after + those changes, so example code may reference APIs from v0.1.3 that differ from + the current release. - **.env is gitignored** — Confirmed: `.env`, `.env.*`, `*.env` all in `.gitignore`. No secret files present in the repo. - **Node >=18 required** — Package uses ESM (`"type": "module"`).