← NeoSigmaCONTENT HISTORY

Update to NeoSigma

Snapshot Nov 17, 2026 · 00:13 UTC · version 1.7.3

Collection source: downloaded plugin package.

WHAT CHANGED

First saved snapshot

No earlier snapshot is available to establish a change.

Save NeoSigma and check future changes in Following.

Up to 3 plugins free · no card required.

Compare saved observations

Download comparison JSON
Full technical diff · 0 changed fields
Full snapshot data
{
  "description": "Integrates the NeoSigma SDKs into a codebase so traces and product events flow into NeoSigma. Activates on requests like \"integrate NeoSigma\", \"add NeoSigma tracing to this app\", \"migrate us off the old neosigma-sdk package\", \"get our traces into NeoSigma\", \"onboard this codebase to NeoSigma\", \"set up the NeoSigma SDK\", \"send product events to NeoSigma\", \"wire NeoSigma into our existing OpenTelemetry setup\", or \"dual export to NeoSigma and another backend\". Do NOT use for analyzing traces already in NeoSigma, building evals, or developing the NeoSigma platform itself.",
  "included_files": [
    {
      "relative_path": "references/python-tracing.md",
      "size_in_bytes": 21374
    },
    {
      "relative_path": "references/typescript-events.md",
      "size_in_bytes": 6032
    },
    {
      "relative_path": "references/typescript-tracing.md",
      "size_in_bytes": 32085
    }
  ],
  "name": "integrate-sdk",
  "skill_md_contents": "---\nname: integrate-sdk\ndescription: Integrates the NeoSigma SDKs into a codebase so traces and product events flow into NeoSigma. Activates on requests like \"integrate NeoSigma\", \"add NeoSigma tracing to this app\", \"migrate us off the old neosigma-sdk package\", \"get our traces into NeoSigma\", \"onboard this codebase to NeoSigma\", \"set up the NeoSigma SDK\", \"send product events to NeoSigma\", \"wire NeoSigma into our existing OpenTelemetry setup\", or \"dual export to NeoSigma and another backend\". Do NOT use for analyzing traces already in NeoSigma, building evals, or developing the NeoSigma platform itself.\n---\n\n# Integrate the NeoSigma SDK\n\nWhen activated, instrument the attached codebase with the NeoSigma SDKs so\nevery agent run lands in NeoSigma as a trace and, where the app emits them,\nproduct events join those traces. Work from the reference files in this skill,\nnot from memory: the SDK surface is small and exact, and plausible-looking\nparameters that are not in the references do not exist. The output is working\ninstrumentation code in the codebase plus a verification that spans\nreached NeoSigma.\n\n## Core principles\n\n1. **References first, memory never.** Read the matching reference file before\n   writing any SDK call. Do not invent parameters, wrappers, or attribute\n   names beyond what the references state. If something is missing, stop rather\n   than guessing.\n2. **Instrument the real path.** Find the route, job, queue consumer, or CLI\n   command that actually runs the agent, and instrument that. Do not build a\n   parallel demo.\n3. **One turn per user message.** NeoSigma's unit is the turn: one user\n   message plus everything the agent did in response, one trace, one\n   `turn_id`. Map the app's own conversation id to `session_id`, its end-user\n   id to `distinct_id`, and reuse its own request/run id as `turn_id` only when\n   that id is one-to-one with a user message.\n4. **Prefer supported integrations over manual spans.** Managed Agents, the\n   Claude Agent SDK, and raw Anthropic/OpenAI clients have dedicated capture\n   paths. FastAPI middleware opens the turn; a provider adapter or\n   auto-instrumentor captures model calls, and `tool()` captures remaining\n   tools.\n5. **Never break the existing telemetry.** Both SDKs build their own private\n   provider by default, so NeoSigma runs alongside an existing OpenTelemetry\n   setup without changing it and without capturing its spans. Neither SDK has an\n   attach option. For dual export of the agent trace to the other backend too,\n   in TypeScript pass the other backend's processor through `extraSpanProcessors`\n   (or use the `tracerProvider` handoff); in Python use the `tracer_provider`\n   handoff per that reference. Either way, do not replace or reorder the app's\n   own OpenTelemetry setup, and verify both destinations.\n6. **Keys stay out of chat and out of code.** Ask the user to set\n   `NEOSIGMA_API_KEY` (an `ns_live_...` key from Settings > Developer > API\n   Keys) in their environment. Never paste a key into a file or a message.\n   Without a key there is no network export, so merged instrumentation is safe\n   in environments that lack one. Console span export remains available for\n   local shape verification.\n7. **Verify with evidence, not code review.** Finish by running one real\n   request and confirming the trace in NeoSigma (or spans on stdout via\n   console export locally). For Next.js, also run `next build` after the\n   integration and keep the SDK out of client and Edge code. Instrumentation\n   that has not produced a visible trace is not done.\n\n## Workflow\n\n0. **Route by language and surface.** Both SDKs do full agent tracing AND\n   product events. Agent traces from Python: use\n   [references/python-tracing.md](references/python-tracing.md). Agent traces\n   from TypeScript/Node: use\n   [references/typescript-tracing.md](references/typescript-tracing.md).\n   Product events: Python's are in\n   [references/python-tracing.md](references/python-tracing.md) (section 8);\n   TypeScript's, with more depth, in\n   [references/typescript-events.md](references/typescript-events.md). A\n   full-stack app usually needs the tracing reference for its agent's language\n   plus the events reference for wherever events are emitted, correlated per\n   principle 3. If the agent code is in neither language, say so and stop; do\n   not improvise an SDK.\n1. **Assess the codebase** per the matching reference's section 1 (execution\n   path, LLM surface, existing OpenTelemetry, the app's own ids).\n2. **Instrument** following the reference exactly: preserve any existing\n   OpenTelemetry provider first, then add SDK lifecycle, the capture surface\n   per component, and id correlation.\n3. **Run one real request and verify** per the reference's verification\n   section. Fix until the trace (and events, if any) are visible.\n4. **Report** using the output format below.\n\n## Use case references\n\n- Python tracing (turns, adapters, auto-instrumentation, FastAPI middleware,\n  the private-default provider and dual export via the `tracer_provider` handoff,\n  product events via `capture()`/`identify()`, lifecycle, verification):\n  [references/python-tracing.md](references/python-tracing.md)\n- TypeScript tracing (turns, the Vercel AI SDK / LangChain / Claude Agent SDK /\n  Managed Agents adapters, the private-default provider and dual export via\n  `extraSpanProcessors`, flush-by-runtime-shape, verification):\n  [references/typescript-tracing.md](references/typescript-tracing.md)\n- TypeScript product events (capture/identify, binding turns, concurrency,\n  serverless, shutdown): [references/typescript-events.md](references/typescript-events.md)\n- Correlating across the SDKs: the references share the id model in principle 3.\n  A `turnId`/`turn_id` for the same user message must match verbatim across\n  languages; ids are camelCase in TypeScript code and snake_case on the wire.\n\n## Output format\n\nDeliver: (1) the instrumentation diff, following the repo's existing code\nstyle; (2) a short summary listing which surface was used per\ncomponent (adapter, flag, middleware, or manual turns) and the id mapping\nchosen (`session_id`/`turn_id`/`distinct_id` sources); (3) the verification\nresult: what was run and where the trace was observed. Do NOT include: API\nkeys, invented SDK parameters, speculative claims about SDK behavior not in\nthe references, or instrumentation for code paths the app does not execute.\n\n## Examples\n\n**Happy path.** \"Add NeoSigma tracing to our FastAPI support bot\" with a raw\nAnthropic client and two tool functions. Read the Python reference. Install\nthe `[instrumentation]` extra, wire `neosigma.init(tracing_enabled=True)` at\nstartup and `shutdown()` on exit,\nopen one `turn()` per request in the chat handler (session/user/message ids\nfrom the request), decorate the tool functions with `@neosigma.tool()`, run\none request with console export, then confirm the trace in NeoSigma.\n\n**Happy path (TypeScript).** \"Add NeoSigma tracing to our Node chatbot\" that\nuses LangChain, with the Vercel AI SDK in one path. Read the TypeScript tracing\nreference. Call `init()` and `installShutdownHandlers()` at startup (long-running\nserver), open a `turn()` per request in the chat route (session/user/message ids\nfrom the request), and pass `neosigmaCallbackHandler()` in the LangChain\n`callbacks`. For the AI SDK path, install `@ai-sdk/otel` and use `wrapAISDK(ai)`,\nor that path emits no spans. Run one request with `NEOSIGMA_CONSOLE_EXPORT=true` plus `await flush()`\nto see the spans, then confirm the trace in NeoSigma.\n\n**Edge case: existing OpenTelemetry.** The app already installs its own\nTracerProvider exporting to another backend. Both SDKs build their own private\nprovider by default and coexist with it automatically, no flag, without\ncapturing its spans, so call `init()` as usual. There is no attach option\n(removed in both SDKs). For dual export of the agent trace to that backend too,\nin TypeScript pass `extraSpanProcessors` (or the `tracerProvider` handoff); in\nPython use the `tracer_provider` handoff, building one provider with\n`CorrelationSpanProcessor` before `NeoSigmaSpanProcessor` plus your exporter.\nVerify both destinations receive data.\n\n**Edge case: no key available in the session.** The user has not provisioned\nan API key. Complete the instrumentation anyway (nothing is sent to NeoSigma\nwithout a key), verify span shape locally with\n`NEOSIGMA_CONSOLE_EXPORT=true`, and tell the user which env var to set in each\nenvironment to turn exporting on.\n"
}

SHA-256 of public snapshot: f4834ced4bc8419066c0544329fe1ff4ea7247c4824a0b292cf458b8393cf23d