risicare 0.2.0 → 0.2.2

package/README.md

@@ -1,57 +1,147 @@
-# Risicare
+# risicare
 
-Self-healing observability for AI agents. Captures decision-level traces, diagnoses failures, and deploys fixes — automatically.
+AI agent observability and self-healing for Node.js and TypeScript.
 
 [![npm version](https://img.shields.io/npm/v/risicare.svg)](https://www.npmjs.com/package/risicare)
-[![Node.js](https://img.shields.io/node/v/risicare.svg)](https://www.npmjs.com/package/risicare)
+[![npm downloads](https://img.shields.io/npm/dm/risicare.svg)](https://www.npmjs.com/package/risicare)
+[![TypeScript](https://img.shields.io/badge/TypeScript-ready-blue.svg)](https://www.npmjs.com/package/risicare)
+[![License: MIT](https://img.shields.io/npm/l/risicare.svg)](https://opensource.org/licenses/MIT)
 
-## Quick Start
+Monitor your AI agents in production. Trace every LLM call, detect errors automatically, and get AI-generated fixes — with 3 lines of setup.
+
+## Quickstart
 
 ```bash
 npm install risicare
 ```
 
 ```typescript
-import { init } from 'risicare';
+import { init, agent, shutdown } from 'risicare';
+import { patchOpenAI } from 'risicare/openai';
+import OpenAI from 'openai';
 
+// 1. Initialize
 init({
   apiKey: 'rsk-...',
   endpoint: 'https://app.risicare.ai',
 });
 
-// That's it. LLM calls are now traced automatically.
+// 2. Patch your LLM client
+const openai = patchOpenAI(new OpenAI());
+
+// 3. Wrap your agent — all LLM calls inside are traced automatically
+const myAgent = agent({ name: 'research-agent' }, async (query: string) => {
+  const response = await openai.chat.completions.create({
+    model: 'gpt-4',
+    messages: [{ role: 'user', content: query }],
+  });
+  return response.choices[0].message.content;
+});
+
+// Run it — traces appear in your dashboard instantly
+const result = await myAgent('What is quantum computing?');
+await shutdown();
 ```
 
-## Provider Instrumentation
+**That's it.** Your agent's LLM calls, latency, token usage, and costs now appear in the [Risicare dashboard](https://app.risicare.ai).
+
+## Features
+
+- **12 LLM providers** — OpenAI, Anthropic, Google, Mistral, Groq, Cohere, Together, Ollama, HuggingFace, Cerebras, Bedrock, Vercel AI
+- **4 framework integrations** — LangChain, LangGraph, Instructor, LlamaIndex
+- **Self-healing** — Automatic error diagnosis and AI-generated fix suggestions
+- **Evaluation scores** — Rate agent quality with `score()` and 13 built-in scorers
+- **Streaming support** — `tracedStream()` for async iterator tracing
+- **Context propagation** — Automatic across `async/await`, `Promise`, `setTimeout`, `EventEmitter`
+- **Zero runtime dependencies** — No bloat in your node_modules
+- **Dual CJS/ESM** — Works with `require()` and `import`
+- **Full TypeScript** — Strict types and IntelliSense out of the box
+- **Non-blocking** — Async batch export with circuit breaker and retry
+- **Zero overhead when disabled** — Frozen NOOP_SPAN singleton, no allocations
 
-Wrap your provider client to auto-capture all LLM calls:
+## LLM Providers
 
 ```typescript
 import { patchOpenAI } from 'risicare/openai';
-import OpenAI from 'openai';
+import { patchAnthropic } from 'risicare/anthropic';
+import { patchGoogle } from 'risicare/google';
+// ... and 9 more
 
 const openai = patchOpenAI(new OpenAI());
-// All chat.completions.create and embeddings calls are now traced.
+// Every call is now traced — model, tokens, latency, cost
 ```
 
-### Supported Providers
+All 12 providers:
 
-| Provider | Import |
-|----------|--------|
-| OpenAI | `risicare/openai` |
-| Anthropic | `risicare/anthropic` |
-| Vercel AI SDK | `risicare/vercel-ai` |
+`openai` · `anthropic` · `google` · `mistral` · `groq` · `cohere` · `together` · `ollama` · `huggingface` · `cerebras` · `bedrock` · `vercel-ai`
 
-## Decorators
+## Framework Integrations
+
+```typescript
+// LangChain
+import { RisicareCallbackHandler } from 'risicare/langchain';
+const handler = new RisicareCallbackHandler();
+await chain.invoke(input, { callbacks: [handler] });
+
+// LangGraph
+import { instrumentLangGraph } from 'risicare/langgraph';
+const tracedGraph = instrumentLangGraph(compiledGraph);
+
+// Instructor
+import { patchInstructor } from 'risicare/instructor';
+const client = patchInstructor(instructor);
+
+// LlamaIndex
+import { RisicareLlamaIndexHandler } from 'risicare/llamaindex';
+```
 
-Structure your traces with agent identity and decision phases:
+## Core API
 
 ```typescript
-import { agent, session, traceThink, traceDecide, traceAct } from 'risicare';
+import {
+  init, shutdown,                         // Lifecycle
+  agent, session,                         // Identity & grouping
+  traceThink, traceDecide, traceAct,      // Decision phases
+  reportError, score,                     // Self-healing & evaluation
+  tracedStream,                           // Streaming
+} from 'risicare';
+
+init({ apiKey, endpoint })                // Initialize SDK
+agent({ name }, fn)                       // Wrap function with agent identity
+session({ sessionId, userId }, fn)        // Group traces into user sessions
+traceThink('analyze', async () => {...})  // Tag reasoning phase
+traceDecide('choose', async () => {...})  // Tag decision phase
+traceAct('execute', async () => {...})    // Tag action phase
+reportError(error)                        // Report caught errors for diagnosis
+score(traceId, 'quality', 0.92)           // Record evaluation score [0.0-1.0]
+tracedStream(asyncIterable, 'stream')     // Trace async iterators
+await shutdown()                          // Flush pending spans and close
+```
+
+## Self-Healing
+
+When your agent fails, Risicare automatically:
+
+1. **Classifies** the error (154 codes across TOOL, MEMORY, REASONING, OUTPUT, etc.)
+2. **Diagnoses** the root cause using AI analysis
+3. **Generates** a fix you can review and apply
+
+```typescript
+try {
+  await myAgent(input);
+} catch (error) {
+  reportError(error); // Triggers automatic diagnosis pipeline
+}
+```
+
+## Decision Phases
+
+Structure your traces to see how your agent thinks, decides, and acts:
 
+```typescript
 const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) => {
   const analysis = await traceThink('analyze', async () => {
-    return await openai.chat.completions.create({ ... });
+    return await openai.chat.completions.create({ /* ... */ });
   });
 
   const decision = await traceDecide('choose-action', async () => {
@@ -62,38 +152,34 @@ const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) =>
     return executeAction(decision);
   });
 });
-
-// Wrap in a session for user-level tracking
-const result = await session({ userId: 'user-123' }, () => myAgent(input));
 ```
 
-## Features
-
-- **Zero runtime dependencies** — no bloat in your node_modules
-- **Dual CJS/ESM** — works with CommonJS `require()` and ES module `import`
-- **Full TypeScript** — strict types, generics, and IntelliSense out of the box
-- **Non-blocking** — async batch export with circuit breaker and retry
-- **Context propagation** — automatic across `async/await`, `Promise`, `setTimeout`, and `EventEmitter`
-- **Zero overhead when disabled** — frozen NOOP_SPAN singleton, no allocations
+## Sessions
 
-## Progressive Integration
+Group traces from the same user conversation:
 
-| Tier | Effort | What You Get |
-|------|--------|-------------|
-| **Tier 0** | `RISICARE_TRACING=true` (env var) | Auto-instrument all LLM calls |
-| **Tier 1** | `import { init } from 'risicare'` | Explicit config, custom endpoint |
-| **Tier 2** | `agent()` wrapper | Agent identity and hierarchy |
-| **Tier 3** | `session()` wrapper | User session tracking |
-| **Tier 4** | `traceThink / traceDecide / traceAct` | Decision phase visibility |
-| **Tier 5** | `traceMessage / traceDelegate` | Multi-agent communication |
+```typescript
+const result = await session(
+  { sessionId: 'sess-abc123', userId: 'user-456' },
+  () => myAgent(userMessage)
+);
+```
 
 ## Requirements
 
-- Node.js >= 18.0.0
-- TypeScript >= 5.0 (optional, for type checking)
+- Node.js 18+
+- TypeScript 5.0+ (optional, types included)
 
-## Links
+## Documentation
 
-- [Documentation](https://risicare.ai/docs)
-- [Dashboard](https://app.risicare.ai)
+- [Full docs](https://risicare.ai/docs)
+- [Quickstart guide](https://risicare.ai/docs/start/quickstart)
+- [JS SDK reference](https://risicare.ai/docs/reference/js-sdk)
+- [LLM providers](https://risicare.ai/docs/instrument/providers)
+- [Self-healing](https://risicare.ai/docs/heal)
+- [Evaluations](https://risicare.ai/docs/observe/evaluations)
 - [Python SDK](https://pypi.org/project/risicare/)
+
+## License
+
+[MIT](LICENSE)

package/dist/index.cjs

@@ -1264,28 +1264,36 @@ function withPhase(phase, fn) {
 }
 
 // src/decorators/phase.ts
-function phaseWrapper(phase, kind, fn) {
+function phaseWrapper(phase, kind, name, fn) {
   return (...args) => {
     const tracer = getTracer2();
     if (!tracer) {
       return fn(...args);
     }
     return withPhase(phase, () => {
-      return tracer.startSpan({ name: `phase:${phase}`, kind }, () => fn(...args));
+      return tracer.startSpan({ name, kind }, () => fn(...args));
     });
   };
 }
-function traceThink(fn) {
-  return phaseWrapper("think" /* THINK */, "think" /* THINK */, fn);
-}
-function traceDecide(fn) {
-  return phaseWrapper("decide" /* DECIDE */, "decide" /* DECIDE */, fn);
-}
-function traceAct(fn) {
-  return phaseWrapper("act" /* ACT */, "tool_call" /* TOOL_CALL */, fn);
-}
-function traceObserve(fn) {
-  return phaseWrapper("observe" /* OBSERVE */, "observe" /* OBSERVE */, fn);
+function traceThink(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:think`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("think" /* THINK */, "think" /* THINK */, name, fn);
+}
+function traceDecide(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:decide`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("decide" /* DECIDE */, "decide" /* DECIDE */, name, fn);
+}
+function traceAct(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:act`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("act" /* ACT */, "tool_call" /* TOOL_CALL */, name, fn);
+}
+function traceObserve(fnOrName, maybeFn) {
+  const name = typeof fnOrName === "string" ? fnOrName : `phase:observe`;
+  const fn = typeof fnOrName === "function" ? fnOrName : maybeFn;
+  return phaseWrapper("observe" /* OBSERVE */, "observe" /* OBSERVE */, name, fn);
 }
 
 // src/decorators/multi-agent.ts