Changelog & Migration

Current SDK versions and how to upgrade between them.

Current Versions

Python SDK (risicare)

0.1.14 — 2026-06-20

First publish to PyPI since 0.1.12 — folds in the unpublished 0.1.13 (F-704) plus framework-instrumentation truthfulness work and the run-end signal. Backward-compatible — no public symbol removed and no signature changed (top-level __all__ and all integration entry points verified identical to 0.1.12). All new behavior is additive, opt-in, or log-only.

Fixed:

• F-A-023 — framework instrumentation now tells the truth (and works where it silently didn't). Some integrations attached wrappers that never sat on the framework's live call path (base/override shadowing, interface drift, moved patch targets) yet self-reported "instrumented" while emitting zero spans. Reworked all 10 framework integrations (langchain, autogen, langgraph, litellm, llamaindex, dspy, instructor, crewai, pydantic_ai, openai_agents) so that what is reported as instrumented actually emits spans — verified by execution on the published-install path.
• #186 — silent span-drops are now surfaced as a rate-limited WARNING (warn-once per outage) when spans are created but no exporter is configured or the backend is unreachable. No exception is raised.
• F-B-009 / F-B-011 — the import latch now retries after a failed instrumentation attempt, and patch functions are idempotent on retry (no double-wrapping).

Added:

• F-B-012 — SDK run-end signal. @session, @agent, and @trace emit a lifecycle-end marker on context-manager exit (risicare.lifecycle.event=end, entity=session|agent|trace, status=ok|error). Normal exit ⇒ ok; an exception propagating out ⇒ error (the exception is re-raised unchanged). Lets the platform mark sessions ended instead of leaving them implicitly "active forever." Purely additive — an older backend ignores the marker.
• F-704 — graceful-shutdown span flush. init() installs an os.register_at_fork hook (gunicorn --preload / celery prefork) and a SIGTERM handler so buffered spans flush on k8s / Docker / systemd termination (atexit does not fire on SIGTERM). The handler is chained (your existing handler still runs), main-thread-only, and a no-op on Windows.
• Honest instrumentation introspection. get_instrumented_modules() now reports a richer per-module record — state ∈ attempted plus inert and version_compat keys (existing keys unchanged). Gate deploy/health checks on state == "instrumented" rather than is_instrumented(), which stays attempt-based.
• Opt-in strict mode — set RISICARE_STRICT_INSTRUMENTATION=1 to raise InstrumentationError at boot on partial/failed instrumentation instead of proceeding best-effort. Off by default — existing behavior is unchanged unless you set it.

0.1.13 — unpublished (folded into 0.1.14)

Internal version bump for F-704 (os.register_at_fork + SIGTERM-safe flush). Never published to PyPI — its changes shipped as part of 0.1.14.

0.1.11 – 0.1.12 — maintenance releases

Incremental fixes between 0.1.10 and the 0.1.14 publish; 0.1.12 was the last release on PyPI prior to 0.1.14. See the SDK repository CHANGELOG.md for commit-level detail.

0.1.10 — 2026-03-24

Critical fix:

• score() was blocking for up to 5 seconds per call in 0.1.9. Now uses a daemon thread with a shared persistent HTTP client — returns in under 1ms regardless of server availability.

Also includes:

• Client-side validation: score() rejects values outside [0.0, 1.0] with a warning instead of sending to server.
• Server-side validation: out-of-range score values now return HTTP 422 with a clear message.
• All 13 evaluation scorers verified in production (10 pass immediately, 3 require additional configuration).

Upgrade from 0.1.9: If you installed 0.1.9, upgrade immediately to avoid blocking score() calls. Upgrade to the current release — do not pin to 0.1.10:

pip install --upgrade risicare

0.1.9 — 2026-03-22

New features:

• risicare.score(trace_id, name, value): Record custom evaluation scores from your code. Scores appear in the dashboard linked to traces.

Documentation fixes:

• Scorer docs rewritten — removed broken risicare_evaluation imports, replaced with risicare.score() + server-side API patterns
• Fixed Fix Runtime import path (from risicare import init_runtime instead of from risicare.runtime import init_runtime)
• Removed phantom from risicare import diagnose — manual diagnosis uses the REST API

0.1.8 — 2026-03-20

New features:

• report_error(exception): report caught exceptions to the self-healing pipeline. Works both inside and outside traced contexts.
• Client-side error deduplication: standalone report_error() calls suppress duplicate errors (same type + message) for 5 minutes
• In-context error detection: spans worker detects errors reported via report_error() for automatic diagnosis

0.1.7 — 2026-03-07

• Infrastructure-only release (PG least-privilege, diagnosis pipeline fixes)
• No SDK behavior changes from 0.1.6

0.1.6 — 2026-03-03

New features:

• @trace dual-mode: works as both decorator and context manager (with trace("name"):)
• @session gains session_id and auto_generate parameters
• ManagedSpan: tracer.start_span() now returns a ManagedSpan that supports both context manager and standalone .end() usage
• Orphan trace debug warnings when @trace is not used to group LLM calls
• service_name propagation to tracer for span metadata

Bug fixes:

• Import hook deadlock: threading.Lock → threading.RLock across 11 framework integrations
• Sentinel object filtering: OpenAI Omit / Anthropic NotGiven no longer corrupt span attributes and cause span drops
• @agent and phase decorators always set context (removed early return that skipped agent_context() when tracer disabled)

0.1.4 — 2026-02-25

Security fixes (critical — upgrade required):

• 20 security findings remediated (auth, SQL injection, OOM protection)
• Session auth added to 27 previously unprotected dashboard routes
• ClickHouse queries converted to parameterized placeholders (13 functions)
• Gateway rejects spans missing project_id instead of pooling into shared bucket
• Gateway buffer max capacity (100K) with 503 when full

Bug fixes:

• AgentRole enum converted to string in set_attribute() (silent span loss)
• 4 missing LLM fields added to to_dict(): temperature, max_tokens, stop_reason, confidence
• JSON serialization errors now logged instead of silently swallowed

0.1.2 — 2026-02-23

• Together AI v2.2+ CompletionsResource detection

0.1.1 — 2026-02-23

• project_id deprecated — emits DeprecationWarning when passed to init()
• hash() → hashlib.md5() for deterministic A/B bucketing across restarts
• Fix content truncated to 10K characters

0.1.0 — 2026-02-02

Initial release.

• Auto-instrumentation via import hooks for 12 LLM providers
• 10 framework integrations (LangChain, LangGraph, CrewAI, AutoGen, etc.)
• Progressive integration Tiers 0–5
• Batch span export with configurable batch_size (clamped to 1–10,000)
• sample_rate with deterministic head-based sampling

JavaScript SDK (risicare npm)

0.4.2 — 2026-06-20

First publish to npm since 0.4.0 — folds in the unpublished 0.4.1 (PR #155 hardening + GuardRejectedError export) plus the run-end signal. Backward-compatible — no export removed; all subpath exports and decorator signatures unchanged; package exports map identical to 0.4.0.

Added:

• F-B-012 — SDK run-end signal (parity with Python 0.1.14). agent(), session(), traceThink/Decide/Act/Observe, and the multi-agent wrappers emit a lifecycle-end marker on completion (risicare.lifecycle.event=end, entity=session|agent|trace, status=ok|error). Normal completion ⇒ ok; a thrown error ⇒ error (the error is re-thrown unchanged). New src/lifecycle.ts. Purely additive — an older backend ignores the marker.
• GuardRejectedError is now a public root export (import { GuardRejectedError } from 'risicare') — thrown by the fix interceptor when a guard rejects an LLM call (fail-closed), and re-thrown by provider patches so the call is never made. (Originally the 0.4.1 intent.)

Fixed:

• PR #155 — JS SDK hardening (16 audit findings closed). Input and robustness hardening across the SDK. (Originally the 0.4.1 intent; released here.)

0.4.1 — unpublished (folded into 0.4.2)

Internal bump for PR #155 (JS SDK hardening, 16 findings) + the public GuardRejectedError export. Never published to npm — released as part of 0.4.2.

0.4.0 — 2026-05-23

Webhook signature verification:

• verifyWebhookSignature() and WebhookVerificationError are now public root exports. The verifier is synchronous, built on Node's crypto, and validates the Stripe-style t={ts},v1={hex} HMAC-SHA256 signature with a configurable timestamp-skew window and constant-time comparison — reaching parity with the Python SDK's verify_webhook_signature. Available via npm install risicare.

0.3.0 — 2026-03-28

4 critical parity fixes + stress tests:

• Trace ID consistency (P0): getTraceContext().traceId now matches the next span's trace ID. Pre-allocates _rootTraceId in context. Fixes score() targeting wrong trace.
• LangChain dedup (P1): RisicareCallbackHandler.withSuppression() prevents duplicate spans when used alongside patchOpenAI(). Same pattern as LlamaIndex handler.
• reportError() dedup (P1): SHA256 fingerprint with 5-minute TTL, 1000-entry cap. 10x same error creates 1 span. Matches Python SDK.
• Provider attribute depth (P1): All 12 providers now capture 11 gen_ai.* attributes (was 4). Includes gen_ai.request.model, gen_ai.request.temperature, gen_ai.usage.prompt_tokens, gen_ai.usage.completion_tokens, gen_ai.usage.total_tokens, gen_ai.response.finish_reasons, llm.cost.total_usd.
• score() NaN fix: Number.isFinite() check rejects NaN and Infinity values.
• FixRuntime subsystem: FixLoader, FixApplier, FixCache, FixInterceptor implemented (not connected to init()).
• 58 stress tests: Wire format, lifecycle edge cases, concurrency (100 tasks), context propagation (async generators, EventEmitter), memory safety, provider edge cases. Total: 483 tests, 51 files, 0 failures.

0.2.2 — 2026-03-27

• npm README rewritten for developer onboarding (conversion-focused with quickstart, all 12 providers, 4 frameworks)
• package.json metadata updated (description, keywords, homepage, bugs URL)

0.2.1 — 2026-03-26

Bug fix:

• Phase decorators (traceThink, traceDecide, traceAct, traceObserve) now accept an optional name parameter: traceThink("analyze", fn) in addition to the bare form traceThink(fn).

0.2.0 — 2026-03-26

Major release — full provider and framework parity with Python SDK.

Providers (3 → 12):

• Added 9 native providers: Google Gemini (patchGoogleAI), Mistral (patchMistral), Groq (patchGroq), Cohere (patchCohere), Together AI (patchTogether), Ollama (patchOllama), HuggingFace (patchHuggingFace), Cerebras (patchCerebras), AWS Bedrock (patchBedrock)
• 8 OpenAI-compatible hosts detected by base URL via patchOpenAI(): DeepSeek, Together AI, Groq, xAI, Fireworks, Baseten, Novita, BytePlus (any other compatible endpoint, e.g. self-hosted vLLM, is traced generically)

Frameworks (0 → 4):

• LangChain.js: RisicareCallbackHandler from risicare/langchain
• LangGraph.js: instrumentLangGraph() from risicare/langgraph
• Instructor: patchInstructor() from risicare/instructor
• LlamaIndex.TS: RisicareLlamaIndexHandler from risicare/llamaindex

Other:

• tracedStream() utility for tracing async iterables
• Dedup infrastructure (suppressProviderInstrumentation)
• AgentRole expanded to 14 values, MessageType to 18 values
• 404 tests passing

0.1.5 — 2026-03-25

Bug fixes:

• Fixed context propagation — withSession(), withAgent(), and withPhase() now work without requiring init(). Previously, context was silently skipped when the SDK wasn't initialized, causing unreliable session/agent tracking.

New features:

• reportError(error, options?) — report caught exceptions for diagnosis. Creates an error span that triggers the self-healing pipeline. Never throws.
• score(traceId, name, value, options?) — send custom evaluation scores. Validates range [0.0, 1.0], non-blocking. Never throws.

0.1.4 — 2026-02-27

• project_id deprecated — emits console.warn when passed to init()
• Version bump to align with Python SDK audit fixes

0.1.2 — 2026-02-22

• Agent role, parent agent ID, session user ID propagated as span attributes (Python parity)
• extractTraceContext keys normalized to camelCase
• getCurrentContext() expanded with all stored fields
• Phase decorators use correct SpanKind (THINK/DECIDE/TOOL_CALL/OBSERVE) instead of INTERNAL
• REFLECT, COMMUNICATE, COORDINATE added to SemanticPhase enum

0.1.1 — 2026-02-21

Critical fixes:

• Provider bundle isolation: singletons moved to globalThis so sub-path exports share tracer state
• traceContent config wired through to Tracer
• Process listener leak fixed (.once() + cleanup on shutdown)
• Failed export batches re-queued with 3-retry limit before drop
• Shutdown race condition: Promise-based dedup replaces boolean flag
• Circuit breaker: half-open state sends 1 probe, not full retry loop
• Anthropic/Vercel AI SpanKind: CLIENT → LLM_CALL
• getMetrics() exposed in public API

0.1.0 — 2026-02-15

Initial release.

• OpenAI, Anthropic, Vercel AI SDK provider instrumentations
• AsyncLocalStorage-based context propagation
• agent(), session(), phase decorators as higher-order functions
• BatchSpanProcessor with HTTP exporter

Migration Guides

Upgrading from 0.1.2 or earlier to 0.1.4+

project_id deprecated:

# Before (0.1.2)
risicare.init(
    api_key="rsk-...",
    project_id="my-project",  # ⚠️ DeprecationWarning
)
 
# After (0.1.4+)
risicare.init(
    api_key="rsk-...",
    service_name="my-agent",
    environment="production",
)

The gateway determines your project from the API key. Use service_name and environment for organization within a project.

Upgrading from 0.1.4 to 0.1.6+

No breaking changes. New features are additive:

# New: @trace as context manager
from risicare import trace
 
with trace("my-operation"):
    result = do_work()
 
# New: @session with fixed ID
from risicare import session
 
@session(session_id="fixed-id")
def handle(query):
    pass
 
# New: @session with auto-generated ID
@session(auto_generate=True)
def handle(query):
    pass

Version Compatibility

Next Steps