{"_id":"@agentic-engineering-agency/paperclip-plugin-langfuse-export","name":"@agentic-engineering-agency/paperclip-plugin-langfuse-export","dist-tags":{"latest":"0.3.0"},"versions":{"0.3.0":{"name":"@agentic-engineering-agency/paperclip-plugin-langfuse-export","version":"0.3.0","description":"Paperclip trace export plugin for Langfuse.","type":"module","exports":{".":"./dist/index.js"},"paperclipPlugin":{"manifest":"./dist/manifest.js","worker":"./dist/worker.js"},"scripts":{"build":"tsc","clean":"rm -rf dist","test":"vitest run","typecheck":"tsc --noEmit"},"dependencies":{"@paperclipai/plugin-sdk":"2026.626.0"},"devDependencies":{"@types/node":"^24.6.0","typescript":"^5.7.3","vitest":"^3.2.4"},"license":"MIT","gitHead":"18fb978f0ddd5bc08c37ed1748610df2640cd52e","_id":"@agentic-engineering-agency/paperclip-plugin-langfuse-export@0.3.0","_nodeVersion":"26.4.0","_npmVersion":"11.17.0","dist":{"integrity":"sha512-xHGuXAQZ/I4hOg0NUyVyTJ6KnkkaJuY/bliMl2QgBeGnIbXsRTljRbZpPYWPiaGstMHAXRug2JkXJIBMp8ihTA==","shasum":"b7c392493c8635ee4a12986573f86f16262587f2","tarball":"https://registry.npmjs.org/@agentic-engineering-agency/paperclip-plugin-langfuse-export/-/paperclip-plugin-langfuse-export-0.3.0.tgz","fileCount":18,"unpackedSize":31021,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIA61XBPB4c1vQOATfTRGYI1aNPelWe64eouxlUDwvGxJAiEA5ejLq2aSbYNWdbiweoCYO+tFqWIONozSxHIcbzyyzQo="}]},"_npmUser":{"name":"lalolalo1873","email":"eduardo.lalo1999@gmail.com"},"directories":{},"maintainers":[{"name":"lalolalo1873","email":"eduardo.lalo1999@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/paperclip-plugin-langfuse-export_0.3.0_1783579567480_0.6571777690134171"},"_hasShrinkwrap":false}},"time":{"created":"2026-07-09T06:46:07.280Z","0.3.0":"2026-07-09T06:46:07.625Z","modified":"2026-07-09T06:46:07.971Z"},"maintainers":[{"name":"lalolalo1873","email":"eduardo.lalo1999@gmail.com"}],"description":"Paperclip trace export plugin for Langfuse.","license":"MIT","readme":"# @agentic-engineering-agency/paperclip-plugin-langfuse-export\n\nExports Paperclip trace-shaped events to [Langfuse](https://langfuse.com) ingestion, following Langfuse tracing best practices.\n\n## Configuration\n\nSet instance config or environment variables:\n\n- `LANGFUSE_PUBLIC_KEY`\n- `LANGFUSE_SECRET_KEY`\n- `LANGFUSE_BASE_URL` (optional, defaults to `https://cloud.langfuse.com`)\n- `LANGFUSE_TRACING_ENVIRONMENT` (optional, defaults to `production`) — tags every trace/observation so you can separate prod/dev in the UI. See https://langfuse.com/docs/tracing-features/environments\n- `LANGFUSE_RELEASE` (optional) — release/version tag applied to every trace for version filtering.\n\nMissing keys disable export without failing Paperclip core work.\n\n## What gets traced\n\nEach Paperclip event produces a Langfuse **trace** plus one **observation**, following the baseline instrumentation requirements (model name, token usage, descriptive names, correct observation types, explicit input/output):\n\n| Paperclip event | Langfuse observation | Why |\n| --- | --- | --- |\n| Has `model` or token counts | `generation-create` | Marks LLM calls as generations so Langfuse computes **cost** from native `usageDetails` ({input, output, total}) and runs model analytics. https://langfuse.com/docs/observability/features/token-and-cost-tracking |\n| Has `toolName` | `span-create` (`tool:<name>`) | Nests tool calls as spans in the trace tree. |\n| Otherwise | `event-create` | Point-in-time events. |\n\nThe **trace** envelope carries the cross-cutting context Langfuse groups and filters on:\n\n- `sessionId` — groups a run's events into one conversation in the **Sessions** view. https://langfuse.com/docs/tracing-features/sessions\n- `userId` (falls back to `agentId`) — enables the **Users** view and per-user cost attribution. https://langfuse.com/docs/tracing-features/users\n- `tags` — free-form filtering (feature, tier, ...). https://langfuse.com/docs/tracing-features/tags\n- `environment` / `release` — deployment separation and version filtering.\n- `input` / `output` — set **explicitly** from the event (not a dump of all metadata), so traces stay readable and args/configs are not leaked. Token/cost data lives in `usageDetails`, not metadata.\n\n`traceId` precedence: `runId → sessionId → issueId → companyId → \"paperclip\"`, so all events from one run land on one trace.\n\n## Worker API\n\nThe worker registers the `exportTrace` data action. It accepts a Paperclip trace event (company/project/issue/agent/session/run/heartbeat/tool identifiers, optional `model`/`inputTokens`/`outputTokens`/`modelParameters`, explicit `input`/`output`, `userId`, `tags`, `environment`, cost, error), maps it to trace + observation events, queues them in memory, and posts batches of up to 50 to `/api/public/ingestion`.\n\nSuccessful Langfuse requests remove the sent batch from the queue. Failed requests put the batch back at the front, keep events queued for a later `exportTrace` call, and log a warning; they never throw through the plugin action. The retry queue is capped at 1000 events so a persistently failing endpoint cannot grow memory unbounded — when full, the oldest events are dropped with a warning. Credentials are only ever used to build the Basic auth header and are never logged.\n\n## Verify\n\n```sh\nnpm install\nnpm test\nnpm run typecheck\n```\n","readmeFilename":"README.md","_rev":"1-9b1e5001d9e628bac29a856b569235ba"}