{"_id":"@altamsh04/openref","_rev":"3-f6e248995266ee3039b1f37de9ad0ba2","name":"@altamsh04/openref","dist-tags":{"latest":"1.2.0"},"versions":{"1.0.0":{"name":"@altamsh04/openref","version":"1.0.0","keywords":["search","agent","web","sources","nlp"],"license":"MIT","_id":"@altamsh04/openref@1.0.0","maintainers":[{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"}],"dist":{"shasum":"282bcb2ac8c9f46e4d9a38b5fba72e7961ae3fac","tarball":"https://registry.npmjs.org/@altamsh04/openref/-/openref-1.0.0.tgz","fileCount":38,"integrity":"sha512-dlzQmGGgk5YFmlNf3naBiQ9bArTzKNZOG/8d14zLMj+RTvrj1Cf3593aixJbW69bWeHJArs38HObpD4EetCCgw==","signatures":[{"sig":"MEQCIFNzNyMWjf252IVTs6rqRH1hpoHQ4wtnqSfowcHiX/IpAiBqSBSdQJqzp3azCGrzONz+IhShO7uqOmJw32002t2teg==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":98702},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"2eba9f2c43ad4d0db48d351ee5af651004914ce9","scripts":{"dev":"tsc --watch","build":"tsc","prepublishOnly":"rm -rf dist && npm run build"},"_npmUser":{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"},"_npmVersion":"10.9.4","description":"Agentic web sources search SDK — turns natural language queries into ranked sources","directories":{},"_nodeVersion":"22.21.1","dependencies":{"openai":"^4.78.1","cheerio":"^1.2.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.3","@types/node":"^22.10.5"},"_npmOperationalInternal":{"tmp":"tmp/openref_1.0.0_1772490367241_0.4931168343625394","host":"s3://npm-registry-packages-npm-production"}},"1.1.0":{"name":"@altamsh04/openref","version":"1.1.0","keywords":["search","agent","web","sources","nlp"],"license":"MIT","_id":"@altamsh04/openref@1.1.0","maintainers":[{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"}],"dist":{"shasum":"c0e35c401b8748bf9be7ccf696779aa700d371b3","tarball":"https://registry.npmjs.org/@altamsh04/openref/-/openref-1.1.0.tgz","fileCount":38,"integrity":"sha512-moQjyvygAuZd28HzV5rBXOFZU3yPVlC6D8nvdnDqMEQK800NzpBEMJYVivUxiS+KZGPGdH3u4HIEGMYZGadTfw==","signatures":[{"sig":"MEQCIFV/M1Jf3lwsyFtvDQB0LvotzsrSZtZvgraYWvukL9P7AiBJT5qeuKw0hphONjtGO/aNGRSLqKkRKGTCu+PwOOJSpQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":111679},"main":"dist/index.js","types":"dist/index.d.ts","gitHead":"17eebe79f47be3ffd93b735e603e3068f8fb8076","scripts":{"dev":"tsc --watch","build":"tsc","check":"npm run typecheck && npm run test:smoke && npm run test:pack","clean":"rm -rf dist","test:pack":"npm run build && ./scripts/test-pack.sh","typecheck":"tsc --noEmit","test:smoke":"npm run build && node scripts/smoke.js","example:run":"npm run example:build && node dist-example/example/index.js","example:build":"tsc -p tsconfig.example.json","example:stream":"npm run example:build && node dist-example/example/stream.js","prepublishOnly":"npm run clean && npm run check","example:non-stream":"npm run example:build && node dist-example/example/non-stream.js"},"_npmUser":{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"},"_npmVersion":"10.9.4","description":"Agentic web sources search SDK — turns natural language queries into ranked sources","directories":{},"_nodeVersion":"22.21.1","dependencies":{"openai":"^4.78.1","cheerio":"^1.2.0"},"_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.7.3","@types/node":"^22.10.5"},"_npmOperationalInternal":{"tmp":"tmp/openref_1.1.0_1772566571107_0.010155340979155048","host":"s3://npm-registry-packages-npm-production"}},"1.2.0":{"name":"@altamsh04/openref","version":"1.2.0","description":"Agentic web sources search SDK — turns natural language queries into ranked sources","main":"dist/index.js","types":"dist/index.d.ts","scripts":{"clean":"rm -rf dist","build":"tsc","example:build":"tsc -p tsconfig.example.json","example:run":"npm run example:build && node dist-example/example/index.js","example:non-stream":"npm run example:build && node dist-example/example/non-stream.js","example:stream":"npm run example:build && node dist-example/example/stream.js","dev":"tsc --watch","typecheck":"tsc --noEmit","test:smoke":"npm run build && node scripts/smoke.js","test:pack":"npm run build && ./scripts/test-pack.sh","check":"npm run typecheck && npm run test:smoke && npm run test:pack","prepublishOnly":"npm run clean && npm run check"},"keywords":["search","agent","web","sources","nlp"],"license":"MIT","dependencies":{"cheerio":"^1.2.0","openai":"^4.78.1"},"devDependencies":{"@types/node":"^22.10.5","typescript":"^5.7.3"},"_id":"@altamsh04/openref@1.2.0","gitHead":"54fcaafe3c0a912cd52c8b8b0ab58335694de1ce","_nodeVersion":"22.21.1","_npmVersion":"10.9.4","dist":{"integrity":"sha512-toD7hYAfoxBGSWmp+1TAi3AQTMD0Z2YM3zzzYPydDxM4tMLFgMZNFPKM2yXsEtxrd5F7bjavwlzHd77P1M9KVQ==","shasum":"febc6c3025cae94605129013d45f1a1f9a0fa9c0","tarball":"https://registry.npmjs.org/@altamsh04/openref/-/openref-1.2.0.tgz","fileCount":43,"unpackedSize":146461,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIH1u68a3vsP9UTkJPZ3REhuqzOyqQTBR5b4kSbcDiCtAAiEA62YjhC+m1lqeYjFly8ratZrgKFwxj/AIwQbqjYFnOcA="}]},"_npmUser":{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"},"directories":{},"maintainers":[{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/openref_1.2.0_1772657318822_0.004086045282335471"},"_hasShrinkwrap":false}},"time":{"created":"2026-03-02T22:26:07.102Z","modified":"2026-03-04T20:48:39.073Z","1.0.0":"2026-03-02T22:26:07.402Z","1.1.0":"2026-03-03T19:36:11.268Z","1.2.0":"2026-03-04T20:48:38.965Z"},"license":"MIT","keywords":["search","agent","web","sources","nlp"],"description":"Agentic web sources search SDK — turns natural language queries into ranked sources","maintainers":[{"name":"altamsh04","email":"bairagdaraltamsh@gmail.com"}],"readme":"# OpenRef\n\nOpenRef is a production-oriented TypeScript SDK for web-grounded answers with optional inline citations.\n\nIt keeps the runtime model simple:\n\n```text\nQuery -> Web Search -> Content Extraction/Chunking -> Streaming Chat Response\n```\n\n## Features\n\n- Web search with provider fallback (`Brave` -> `DuckDuckGo`)\n- Source deduplication and domain diversity filtering\n- Optional LLM reranking of search candidates\n- Optional LLM query expansion for broader retrieval\n- Query-aware page extraction and chunk scoring\n- Streaming chat response\n- Configurable citation behavior (`citationStrictness`)\n- Typed SDK surface (`search`, `chat`, event streams)\n\n## Install\n\n```bash\nnpm install @altamsh04/openref\n```\n\n## Quick Start\n\n```ts\nimport { OpenRef } from \"@altamsh04/openref\";\n\nconst agent = new OpenRef({\n  llm: {\n    apiKey: \"sk-or-v1......\",\n    chatModel: \"stepfun/step-3.5-flash:free\",\n    fallbackChatModels: [\n      \"nvidia/nemotron-3-nano-30b-a3b:free\",\n      \"mistralai/mistral-small-3.1-24b-instruct:free\"\n    ],\n    systemPrompt: \"Answer in short bullet points.\",\n    citationStrictness: true,\n    maxRetries: 2,\n    retryDelayMs: 1200,\n    maxOutputTokens: 2048,\n    maxContinuationRequests: 2\n  },\n  search: {\n    engineProvider: { provider: \"brave\" }, // fallback order: duckduckgo -> bing\n    preferLatest: true,\n    timeZone: \"America/New_York\",\n    maxSources: 5,\n    queryExpansion: true,\n    queryExpansionValue: 3,\n    queryExpansionTimeout: 1200,\n    searchTimeout: 5000,\n    enableReranking: true,\n    rerankTimeout: 4000\n  },\n  retrieval: {\n    contentTimeout: 6000,\n    maxContextTokens: 6000,\n    chunkTargetTokens: 400\n  },\n  response: {\n    stream: true\n  }\n});\n\nconst query = \"Today's top news in AI\";\n\nasync function run() {\n  // Per-request overrides\n  const response = await agent.chat(query, {\n    stream: false,\n    systemPrompt: \"Keep it under 120 words and mention uncertainty clearly.\",\n    citationStrictness: false\n  });\n\n  console.log(JSON.stringify(response, null, 2));\n}\n\nrun();\n```\n\n## Local Example\n\nRun the local SDK example:\n\n```bash\nOPENROUTER_API_KEY=sk-or-v1-xxxx npm run example:run -- \"Today's top news in AI\"\n```\n\nRun dedicated non-stream and stream examples:\n\n```bash\nOPENROUTER_API_KEY=sk-or-v1-xxxx npm run example:non-stream -- \"What is OpenRouter?\"\nOPENROUTER_API_KEY=sk-or-v1-xxxx npm run example:stream -- \"What is OpenRouter?\"\n```\n\nFiles:\n- `example/index.ts` example app using local source (`../src`)\n- `example/non-stream.ts` non-stream response example\n- `example/stream.ts` stream response example\n- `tsconfig.example.json` example build config\n\n## API\n\n### `new OpenRef(config)`\n\n#### `config.llm`\n- `apiKey?: string` OpenRouter API key. Preferred key location.\n- `chatModel?: string` Primary chat model.\n- `fallbackChatModels?: string[]` Models used if primary model fails.\n- `systemPrompt?: string` Base system instruction for response style/behavior.\n- `citationStrictness?: boolean` Citation policy in response text.\n- `maxRetries?: number` Retry attempts per model request.\n- `retryDelayMs?: number` Backoff delay between retries.\n- `maxOutputTokens?: number` Max tokens per generation request.\n- `maxContinuationRequests?: number` Extra continuation requests when output is truncated.\n\n`citationStrictness` behavior:\n- `true` (default): model is instructed to include inline `[N]` citations for factual claims.\n- `false`: model is instructed to avoid `[N]` citations unless user explicitly asks.\n\n#### `config.search`\n- `preferLatest?: boolean` Adds recency bias to search and prompting.\n- `timeZone?: string` Used for date context formatting.\n- `maxSources?: number` Final number of sources to keep.\n- `queryExpansion?: boolean` Expand user query into subqueries using LLM before retrieval.\n- `queryExpansionValue?: number` Number of expanded subqueries (0-5).\n- `queryExpansionTimeout?: number` Max expansion wait time in ms.\n- `engineProvider?: { provider?: \"brave\" | \"duckduckgo\" | \"bing\" | \"searxng\" | \"searxncg\" | Array<...>, queryUrl?: string }`\n  Choose preferred engine order. If one provider is given (e.g. `\"brave\"`), OpenRef auto-falls back to the other mainstream engines.\n  For `provider: \"searxng\"`, you can pass a custom `queryUrl` (for example `http://localhost:8080/search?q={query}`).\n- `searchTimeout?: number` Search request timeout in ms.\n- `enableReranking?: boolean` Enable LLM reranking for candidates.\n- `rerankTimeout?: number` Reranking timeout in ms.\n\n#### `config.retrieval`\n- `contentTimeout?: number` Page fetch/extraction timeout in ms.\n- `maxContextTokens?: number` Token budget for assembled context.\n- `chunkTargetTokens?: number` Approximate target size of chunks.\n\n#### `config.response`\n- `stream?: boolean` Default chat mode (`true` for event stream, `false` for aggregated response).\n\n### `search(query: string): Promise<SearchResult>`\n\nRuns retrieval and ranking only.\n\n### `chat(query: string, options?)`\n\nPer-request options:\n- `stream?: boolean`\n- `systemPrompt?: string` Overrides constructor `llm.systemPrompt`.\n- `citationStrictness?: boolean` Overrides constructor `llm.citationStrictness`.\n\nWhen `stream: true`, returns `AsyncGenerator<ChatEvent>` with:\n- `expanded_queries` (optional, early event when enabled)\n- `sources`\n- `text` (multiple chunks)\n- `citations`\n- `done`\n\nWhen `stream: false`, returns `Promise<ChatResponse>` with:\n- `text`\n- `sources`\n- `citationMap`\n- `chatTokenUsage`\n- `metadata`\n\n`search()` and `chat(..., { stream: false })` include `metadata.expandedQueries` when query expansion is enabled.\n\n## Legacy Config Support\n\nTop-level fields like `openRouterApiKey`, `chatModel`, `maxSources`, etc. are still accepted for backward compatibility.\n\nPreferred format is grouped config (`llm`, `search`, `retrieval`, `response`).\n\n## Test Before Publish\n\nRun full pre-publish checks:\n\n```bash\nnpm run check\n```\n\nThis runs:\n- `npm run typecheck` (`tsc --noEmit`)\n- `npm run test:smoke` (build + SDK smoke checks)\n- `npm run test:pack` (build + `npm pack` install/import verification in a temp project)\n\n`test:pack` tries a real temp-project install first. If npm registry access is unavailable, it automatically runs an offline tarball import fallback.\n\n### Smoke Test Modes\n\n- Without `OPENROUTER_API_KEY`:\n  - validates constructor/config compatibility (grouped + legacy)\n  - validates API surface (`search`, `chat`)\n  - skips live network requests\n\n- With `OPENROUTER_API_KEY`:\n  - runs live `search`\n  - runs `chat` non-stream\n  - runs `chat` stream and confirms `done` event\n\nExample:\n\n```bash\nOPENROUTER_API_KEY=sk-or-v1-xxxx npm run test:smoke\n```\n\n## Notes\n\n- `query` must be a non-empty string.\n- If no sources are found, `chat` returns a graceful text response with empty citation map.\n- OpenRef uses OpenRouter-compatible chat models for reranking and response generation.\n","readmeFilename":"README.md"}