Changelog & Migration

Current SDK versions and how to upgrade between them.

Current Versions

Python SDK (risicare)

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:

pip install --upgrade risicare==0.1.10

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.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 host-detected providers via patchOpenAI(): DeepSeek, xAI, Fireworks, Baseten, Novita, BytePlus, vLLM, and any OpenAI-compatible API

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