@blackdrome/open-deepresearch 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,18 @@
+# Changelog
+
+## 0.1.0 - 2026-03-02
+
+- Initial standalone release of `@upai/open-deepresearch`.
+- Added full open DeepResearch pipeline:
+  - planning
+  - adaptive retrieval rounds
+  - ranking + domain diversification
+  - claim graphing and contradiction checks
+  - citation-grounded synthesis
+  - truth-contract critique/repair pass
+- Added provider adapters:
+  - OpenRouter (`OpenRouterAdapter`)
+  - NVIDIA NIM (`NimAdapter`)
+  - custom function fallback (`FunctionLlmAdapter`)
+- Added pluggable HTTP JSON search adapter (`HttpJsonSearchAdapter`).
+- Added public factory API (`createOpenDeepResearchEngine`).

package/LICENSE

@@ -0,0 +1,17 @@
+Apache License
+Version 2.0, January 2004
+http://www.apache.org/licenses/
+
+Copyright 2026 BLACKDROME UPAI
+
+Licensed under the Apache License, Version 2.0 (the "License");
+you may not use this file except in compliance with the License.
+You may obtain a copy of the License at
+
+    http://www.apache.org/licenses/LICENSE-2.0
+
+Unless required by applicable law or agreed to in writing, software
+distributed under the License is distributed on an "AS IS" BASIS,
+WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+See the License for the specific language governing permissions and
+limitations under the License.

package/README.md

@@ -0,0 +1,133 @@
+# UPAI Open DeepResearch Engine
+
+Standalone open-source DeepResearch engine with:
+
+- adaptive multi-round retrieval
+- ranking + domain diversification
+- claim clustering + contradiction checks
+- citation-grounded synthesis with critique pass
+- pluggable adapters for search + LLM providers
+- built-in providers for **OpenRouter** and **NVIDIA NIM**
+
+## Install
+
+```bash
+npm install @upai/open-deepresearch
+```
+
+## Quick Start
+
+```ts
+import {
+  HttpJsonSearchAdapter,
+  createOpenDeepResearchEngine,
+} from "@upai/open-deepresearch";
+
+const searchAdapter = new HttpJsonSearchAdapter({
+  endpoint: process.env.SEARCH_ENDPOINT!,
+  apiKey: process.env.SEARCH_API_KEY,
+  apiKeyHeader: "Authorization",
+  staticPayload: { provider: "free", mode: "web", num: 10 },
+});
+
+const engine = createOpenDeepResearchEngine({
+  searchAdapter,
+  defaultProvider: "openrouter",
+  openRouter: {
+    apiKey: process.env.OPENROUTER_API_KEY!,
+    model: process.env.OPENROUTER_MODEL || "openai/gpt-4o-mini",
+  },
+  nim: {
+    apiKey: process.env.NIM_API_KEY!,
+    model: process.env.NIM_MODEL || "meta/llama-3.1-70b-instruct",
+  },
+  fallbackComplete: async (prompt) => {
+    return `Fallback handler received prompt length=${prompt.length}`;
+  },
+});
+
+const run = await engine.run("Best RAG architecture for support chat in 2026", {
+  depth: "deep",
+  providerHint: "openrouter",
+  onProgress: (p) => console.log(`[${p.stage}] ${p.message}`),
+});
+
+console.log(run.finalAnswer);
+console.log(run.sourcesForMessage.slice(0, 5));
+```
+
+## Required API Keys
+
+At minimum, configure one LLM provider and one search endpoint.
+
+### OpenRouter
+
+- `OPENROUTER_API_KEY`
+- `OPENROUTER_MODEL` (example: `openai/gpt-4o-mini`)
+
+### NVIDIA NIM
+
+- `NIM_API_KEY`
+- `NIM_MODEL` (example: `meta/llama-3.1-70b-instruct`)
+
+### Search
+
+Use any endpoint that returns JSON with either:
+
+- `results: [{ title, snippet, url }]`
+- OR `items: [{ title, snippet, url|link }]`
+
+Then configure:
+
+- `SEARCH_ENDPOINT`
+- `SEARCH_API_KEY` (optional, depending on your backend)
+
+## Engine Pipeline
+
+1. **Plan**: Creates multi-angle query set (facts, recency, benchmarks, counterpoints, docs).
+2. **Retrieve**: Executes search with domain/forum constraints.
+3. **Rank**: Scores by relevance + authority + recency + constraint matching.
+4. **Diversify**: Caps per-domain results to avoid over-concentration.
+5. **Verify**: Builds claim graph and finds likely contradictions.
+6. **Synthesize**: Produces direct answer with citations.
+7. **Critique**: Enforces truth contract and repairs response when possible.
+
+## Domain / Forum Constraints
+
+The engine auto-detects constraints from user query language:
+
+- `site:reddit.com best vector db`
+- `only from stack overflow`
+- `discussion on hacker news`
+
+You can also pass explicit constraints in `run(..., { constraints })`.
+
+## Progress Events
+
+`run` supports progress hooks for UI and logs:
+
+```ts
+onProgress: (progress) => {
+  // progress.stage: planning | retrieving | ranking | verifying | synthesizing | critiquing
+}
+```
+
+## Exports
+
+- `OpenDeepResearchEngine`
+- `createOpenDeepResearchEngine`
+- `OpenRouterAdapter`
+- `NimAdapter`
+- `HttpJsonSearchAdapter`
+- `FunctionLlmAdapter`
+- all core types and constraints utilities
+
+## Notes
+
+- Node 20+ recommended.
+- The library uses `fetch` and standard Web APIs.
+- For strict security, keep provider keys server-side.
+
+## License
+
+Apache-2.0