{"_id":"@dosymbek/qcoreai-client","_rev":"2-ab78de83a878882adaf67479ad53dc17","name":"@dosymbek/qcoreai-client","dist-tags":{"latest":"1.0.0"},"versions":{"0.9.0":{"name":"@dosymbek/qcoreai-client","version":"0.9.0","keywords":["aevion","qcoreai","multi-agent","llm","anthropic","openai","gemini","deepseek","grok","sse","webhook"],"author":{"name":"AEVION"},"license":"Apache-2.0","_id":"@dosymbek/qcoreai-client@0.9.0","maintainers":[{"name":"dosymbek","email":"yahiin1978@gmail.com"}],"homepage":"https://aevion.app/qcoreai","bugs":{"url":"https://github.com/Dossymbek281078/AEVION/issues"},"dist":{"shasum":"662a846c03b022d5137cc5153cc9a5bbcab61331","tarball":"https://registry.npmjs.org/@dosymbek/qcoreai-client/-/qcoreai-client-0.9.0.tgz","fileCount":6,"integrity":"sha512-/ASPzYDwD1vV2gOlOfN2MAHGMGjy8CZiJTOr1qknsd13ld6999dthYWQdYLSRYK75EKtdjsno0vGZpdNx2emHg==","signatures":[{"sig":"MEUCIQDZj0CeX8RrTyjDC6EfkxMikorKKo22aZnbp0Qd63cl5gIgWTe+AfI50GSCPtzADpqwJNgUuMr8KNNqED3cqC2n+R0=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":162905},"main":"./dist/index.js","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit"},"_npmUser":{"name":"dosymbek","email":"yahiin1978@gmail.com"},"repository":{"url":"git+https://github.com/Dossymbek281078/AEVION.git","type":"git","directory":"frontend-qcore/packages/qcoreai-client"},"_npmVersion":"11.6.2","description":"TypeScript client for AEVION QCoreAI multi-agent pipeline — sync, streaming, refine, tags, eval harness, prompts library, threading, templates, batch runs, scheduled batches, workspaces, custom pipelines, notebook collections, run insights, cost breakdown","directories":{},"_nodeVersion":"24.11.1","_hasShrinkwrap":false,"devDependencies":{"typescript":"^5.4.0"},"_npmOperationalInternal":{"tmp":"tmp/qcoreai-client_0.9.0_1778238405887_0.26874116368807854","host":"s3://npm-registry-packages-npm-production"}},"1.0.0":{"name":"@dosymbek/qcoreai-client","version":"1.0.0","description":"TypeScript client for AEVION QCoreAI multi-agent pipeline — sync, streaming, refine, tags, eval harness, prompts library, threading, templates, batch runs, scheduled batches, workspaces, custom pipelines, notebook collections, run insights, cost breakdown","license":"Apache-2.0","author":{"name":"AEVION"},"homepage":"https://aevion.app/qcoreai","repository":{"type":"git","url":"git+https://github.com/Dossymbek281078/AEVION.git","directory":"frontend-qcore/packages/qcoreai-client"},"type":"module","main":"./dist/index.js","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"types":"./dist/index.d.ts","import":"./dist/index.js","require":"./dist/index.cjs"}},"scripts":{"build":"tsc -p tsconfig.json","typecheck":"tsc -p tsconfig.json --noEmit","publish:npm":"npm run build && npm publish --access public"},"keywords":["aevion","qcoreai","multi-agent","llm","anthropic","openai","gemini","deepseek","grok","sse","webhook"],"engines":{"node":">=18"},"devDependencies":{"typescript":"^5.4.0"},"_id":"@dosymbek/qcoreai-client@1.0.0","bugs":{"url":"https://github.com/Dossymbek281078/AEVION/issues"},"_nodeVersion":"24.11.1","_npmVersion":"11.6.2","dist":{"integrity":"sha512-KS9uFWWiwJtRelACUujoKQsqnsuaIVBmhbvmEh8vCwaXMmsDvUwLGO0P22hTx7jR9XmSOOlzlVWp6wbXuvqgyg==","shasum":"ef64e86348d584d88dbd18f7037900750afcdafe","tarball":"https://registry.npmjs.org/@dosymbek/qcoreai-client/-/qcoreai-client-1.0.0.tgz","fileCount":6,"unpackedSize":251611,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCIBvtbMmDV0FfRh9aow3azLWn2W+vqoZ2vOi0G8hXiWeSAiBnD6thwkvtIQU5cSlGFGM7DBXs8AtbPTWE88g/znLbXw=="}]},"_npmUser":{"name":"dosymbek","email":"yahiin1978@gmail.com"},"directories":{},"maintainers":[{"name":"dosymbek","email":"yahiin1978@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/qcoreai-client_1.0.0_1778506715540_0.2553141804046615"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-08T11:06:45.758Z","modified":"2026-05-11T13:38:35.785Z","0.9.0":"2026-05-08T11:06:46.048Z","1.0.0":"2026-05-11T13:38:35.687Z"},"bugs":{"url":"https://github.com/Dossymbek281078/AEVION/issues"},"author":{"name":"AEVION"},"license":"Apache-2.0","homepage":"https://aevion.app/qcoreai","keywords":["aevion","qcoreai","multi-agent","llm","anthropic","openai","gemini","deepseek","grok","sse","webhook"],"repository":{"type":"git","url":"git+https://github.com/Dossymbek281078/AEVION.git","directory":"frontend-qcore/packages/qcoreai-client"},"description":"TypeScript client for AEVION QCoreAI multi-agent pipeline — sync, streaming, refine, tags, eval harness, prompts library, threading, templates, batch runs, scheduled batches, workspaces, custom pipelines, notebook collections, run insights, cost breakdown","maintainers":[{"name":"dosymbek","email":"yahiin1978@gmail.com"}],"readme":"# @aevion/qcoreai-client\n\nTypeScript client for [AEVION QCoreAI](https://aevion.app/qcoreai) — a multi-agent LLM pipeline with sequential / parallel / debate strategies, mid-run human guidance, hard cost caps, run tagging and signed webhooks.\n\nSingle-file SDK (~300 LOC). No runtime deps. Works in Node 18+ and modern browsers / Edge.\n\n```bash\nnpm install @aevion/qcoreai-client\n```\n\n## Quick start\n\n```ts\nimport { QCoreClient } from \"@aevion/qcoreai-client\";\n\nconst client = new QCoreClient({\n  baseUrl: \"https://api.aevion.app\",\n  token: process.env.AEVION_TOKEN, // optional, required for owner endpoints\n});\n\n// 1. Sync — collect the whole stream into a final answer.\nconst result = await client.runSync({\n  input: \"Compare Postgres vs DynamoDB for an event-sourced ledger.\",\n  strategy: \"sequential\", // | \"parallel\" | \"debate\"\n  maxCostUsd: 0.10,\n});\n\nconsole.log(result.finalContent);\nconsole.log(\"Cost:\", result.totalCostUsd, \"Run:\", result.runId);\n```\n\n## Streaming\n\n```ts\nfor await (const evt of client.runStream({\n  input: \"Plan a 30-day onboarding for a B2B SaaS\",\n  strategy: \"debate\",\n})) {\n  if (evt.type === \"agent_chunk\") process.stdout.write(evt.delta);\n  if (evt.type === \"run_complete\") {\n    console.log(\"\\n[done]\", evt.totalCostUsd, evt.totalDurationMs + \"ms\");\n  }\n}\n```\n\nEvery event matches the server's `OrchestratorEvent` union — see `src/index.ts` for the exhaustive type. Common types include:\n\n- `session` `{ sessionId, runId }` — emitted first; capture for downstream API calls\n- `agent_start` `{ role, stage, instance?, provider, model }`\n- `agent_chunk` `{ role, stage, delta }` — token deltas\n- `agent_end` `{ role, stage, tokensIn, tokensOut, durationMs, costUsd, content }`\n- `verdict` `{ approved, feedback }` — sequential strategy critic verdict\n- `guidance_applied` `{ nextRole, nextStage, text }` — mid-run user steer landed\n- `cost_cap_hit` `{ spentUsd, capUsd }` — hard cap crossed, run finalised early\n- `run_complete` `{ finalContent, status, totalCostUsd, totalDurationMs }`\n- `error` `{ message }`\n\n## WebSocket duplex (mid-run guidance on the same connection)\n\n```ts\nconst session = client.runWS({\n  input: \"Plan a 30-day onboarding for a B2B SaaS\",\n  strategy: \"debate\",\n});\n\n// Steer mid-run from a separate event handler:\nsetTimeout(() => session.interject(\"Add a TL;DR section at the top\"), 3000);\n\nfor await (const evt of session.events) {\n  if (evt.type === \"chunk\") process.stdout.write(evt.text);\n  if (evt.type === \"guidance_applied\") console.log(\"\\n[steered]\", evt.text);\n}\n```\n\nIn Node 22+ `WebSocket` is a global. For older Node:\n\n```ts\nimport { WebSocket } from \"ws\";\nconst session = client.runWS({ input: \"...\", WebSocketImpl: WebSocket as any });\n```\n\nServer endpoint: `/api/qcoreai/ws`. Auth via `?token=<JWT>`. Rate limit 30 upgrades / minute / IP. 64 KB max message size, 8 pending guidance × 4 KB.\n\n## Refining a run\n\n```ts\n// Apply a one-pass surgical edit on top of an already-finished run.\nawait client.refine(runId, \"Add a TL;DR section at the top.\");\n```\n\n## Tags + search\n\n```ts\nawait client.setTags(runId, [\"investor-deck\", \"ledger-research\"]);\n\n// Substring search across input/finalContent/session.title/tags.\nconst hits = await client.search(\"ledger\");\nhits.forEach((h) => console.log(h.matched, h.preview));\n\n// Top tags ranked by count — drives the sidebar chip strip.\nconst top = await client.topTags(15);\n```\n\n## Daily timeseries (cost forecasting)\n\n```ts\nconst series = await client.timeseries(30);\n// series: [{ date: \"2026-04-22\", runs: 4, costUsd: 0.123 }, ...]\n```\n\n## Agent marketplace\n\n```ts\n// 1. Publish a preset.\nconst { id } = await client.sharePreset({\n  name: \"Investor pitch lineup\",\n  description: \"Sequential — Sonnet writer + Haiku critic\",\n  strategy: \"sequential\",\n  overrides: { writer: { provider: \"anthropic\", model: \"claude-sonnet-4-20250514\" } },\n});\n\n// 2. Browse what others have published.\nconst top = await client.browsePresets();\nconst pitchPresets = await client.browsePresets(\"investor\");\n\n// 3. Import to bump the importCount + use locally.\nconst imported = await client.importPreset(top[0].id);\nconsole.log(\"Got preset:\", imported.name, imported.strategy, imported.overrides);\n\n// 4. (Owner) delete one of your shared presets.\nawait client.deletePreset(id);\n```\n\n## Eval harness\n\nTrack quality regressions by running a fixed suite of test cases through your multi-agent pipeline. Each case has an input prompt and a judge (`contains` / `not_contains` / `equals` / `regex` / `min_length` / `max_length`). The runner aggregates a 0..1 weighted score so you can chart it over time.\n\n```ts\n// 1. Create a suite.\nconst suite = await client.createEvalSuite({\n  name: \"Onboarding writer regression\",\n  description: \"Catch days where the writer drops the TL;DR section\",\n  strategy: \"sequential\",\n  cases: [\n    {\n      id: \"c1\",\n      name: \"Has TL;DR\",\n      input: \"Plan a 30-day onboarding for a B2B SaaS\",\n      judge: { type: \"contains\", needle: \"TL;DR\", caseSensitive: false },\n    },\n    {\n      id: \"c2\",\n      name: \"Min length\",\n      input: \"Plan a 30-day onboarding for a B2B SaaS\",\n      judge: { type: \"min_length\", chars: 800 },\n    },\n    {\n      id: \"c3\",\n      name: \"No banned phrasing\",\n      input: \"Plan a 30-day onboarding for a B2B SaaS\",\n      judge: { type: \"not_contains\", needle: \"as a large language model\" },\n    },\n    {\n      id: \"c4\",\n      name: \"Tone is friendly + actionable\",\n      input: \"Plan a 30-day onboarding for a B2B SaaS\",\n      judge: {\n        type: \"llm_judge\",\n        rubric: \"The output must read as a friendly senior PM giving concrete week-by-week actions.\",\n        passThreshold: 0.7,\n      },\n    },\n  ],\n});\n\n// 2. Run it (and wait for completion).\nconst result = await client.runEvalSuiteAndWait(suite.id, {\n  concurrency: 3,\n  perCaseMaxCostUsd: 0.05,\n  timeoutMs: 5 * 60_000,\n});\n\nconsole.log(`Score: ${(result.score! * 100).toFixed(1)}%`);\nfor (const r of result.results) {\n  console.log(`${r.passed ? \"✔\" : \"✘\"} ${r.caseName} — ${r.reason}`);\n}\n\n// 3. Track regressions over time.\nconst history = await client.listSuiteRuns(suite.id, 30);\nconst trend = history.filter((r) => r.status === \"done\").map((r) => r.score);\nconsole.log(\"Last 30 scores:\", trend);\n```\n\nOr kick off a run without blocking and poll yourself:\n\n```ts\nconst run = await client.runEvalSuite(suite.id);\nwhile (run.status === \"running\") {\n  await new Promise((r) => setTimeout(r, 1500));\n  Object.assign(run, await client.getEvalRun(run.id));\n  console.log(`progress: ${run.results.length}/${run.totalCases}`);\n}\n```\n\n## Per-user webhooks\n\nConfigure a personal webhook that receives `run.completed` events with HMAC signatures.\n\n```ts\nawait client.setUserWebhook(\n  \"https://your-receiver.example.com/qcore\",\n  \"any-strong-shared-secret\"\n);\n```\n\nThe server POSTs a JSON payload to that URL with two headers:\n- `X-QCore-Signature: <hex HMAC-SHA256 of body using your secret>`\n- `X-QCore-Origin: env | user`\n\nVerify it on your receiver:\n\n```ts\nimport { verifyWebhookHmac } from \"@aevion/qcoreai-client\";\nimport express from \"express\";\n\nconst app = express();\n\napp.post(\"/qcore-webhook\", express.raw({ type: \"*/*\" }), async (req, res) => {\n  const ok = await verifyWebhookHmac(\n    req.body,\n    req.headers[\"x-qcore-signature\"],\n    process.env.QCORE_WEBHOOK_SECRET!\n  );\n  if (!ok) return res.status(401).end();\n  const evt = JSON.parse(req.body.toString(\"utf8\"));\n  console.log(\"run.completed\", evt.runId, evt.status, evt.totalCostUsd);\n  res.json({ ok: true });\n});\n```\n\n`verifyWebhookHmac` uses Web Crypto SubtleCrypto + constant-time comparison. Works in Node 18+, Cloudflare Workers, Vercel Edge.\n\n## API reference\n\n| Method | HTTP | Notes |\n|---|---|---|\n| `runSync(opts)` | `POST /api/qcoreai/multi-agent` | Buffers stream into `RunSyncResult` |\n| `runStream(opts)` | `POST /api/qcoreai/multi-agent` | Async generator of `OrchestratorEvent` |\n| `runWS(opts)` | `WS /api/qcoreai/ws` | Duplex: events + `interject(text)` + `stop()` |\n| `sharePreset(opts)` | `POST /api/qcoreai/presets/share` | Auth, returns `{ id }` |\n| `browsePresets(query?, limit?)` | `GET /api/qcoreai/presets/public` | Public catalog |\n| `importPreset(id)` | `POST /api/qcoreai/presets/:id/import` | Bumps importCount |\n| `deletePreset(id)` | `DELETE /api/qcoreai/presets/:id` | Owner-only |\n| `refine(runId, instruction, opts?)` | `POST /api/qcoreai/runs/:id/refine` | One-pass surgical edit |\n| `setTags(runId, tags)` | `PATCH /api/qcoreai/runs/:id/tags` | Owner-only, normalized 16x32 |\n| `search(query, limit?)` | `GET /api/qcoreai/search?q=` | Substring + tag match |\n| `topTags(limit?)` | `GET /api/qcoreai/tags?limit=` | Ranked by usage |\n| `timeseries(days?)` | `GET /api/qcoreai/analytics/timeseries?days=` | Daily buckets |\n| `setUserWebhook(url, secret?)` | `PUT /api/qcoreai/me/webhook` | Auth required |\n| `deleteUserWebhook()` | `DELETE /api/qcoreai/me/webhook` | Auth required |\n| `verifyWebhookHmac(body, sig, secret)` | — | Receiver-side utility |\n| `createEvalSuite(opts)` | `POST /api/qcoreai/eval/suites` | Auth |\n| `listEvalSuites(limit?)` | `GET /api/qcoreai/eval/suites` | Auth |\n| `getEvalSuite(id)` | `GET /api/qcoreai/eval/suites/:id` | Owner |\n| `updateEvalSuite(id, patch)` | `PATCH /api/qcoreai/eval/suites/:id` | Owner |\n| `deleteEvalSuite(id)` | `DELETE /api/qcoreai/eval/suites/:id` | Owner |\n| `runEvalSuite(id, opts?)` | `POST /api/qcoreai/eval/suites/:id/run` | Async, returns in-flight EvalRun |\n| `getEvalRun(id)` | `GET /api/qcoreai/eval/runs/:id` | Poll for progress |\n| `listSuiteRuns(id, limit?)` | `GET /api/qcoreai/eval/suites/:id/runs` | Regression history |\n| `runEvalSuiteAndWait(id, opts?)` | — | Convenience: kick off + poll until done |\n\n## Browser usage\n\nThe client uses standard `fetch` and `ReadableStream` — works in browsers without polyfills. For SSE you can either let the SDK buffer (use `runSync`) or iterate (`runStream`) — same code in Node and browsers.\n\n## Auth\n\nOwner-scoped endpoints (sessions list, run rename/delete, tags, webhook config, search results scoped to your user) require a JWT in `Authorization: Bearer <token>`. Pass the token at construction time or rotate via `setToken`.\n\nThe `runSync` / `runStream` and public `search` (anonymous-only results) work without auth — useful for embedding QCoreAI in unauthenticated public landing pages.\n\n## License\n\nApache-2.0 © AEVION\n","readmeFilename":"README.md"}