risicare 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# Risicare
+
+Self-healing observability for AI agents. Captures decision-level traces, diagnoses failures, and deploys fixes — automatically.
+
+[![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)
+
+## Quick Start
+
+```bash
+npm install risicare
+```
+
+```typescript
+import { init } from 'risicare';
+
+init({
+  apiKey: 'rsk-...',
+  endpoint: 'https://app.risicare.ai',
+});
+
+// That's it. LLM calls are now traced automatically.
+```
+
+## Provider Instrumentation
+
+Wrap your provider client to auto-capture all LLM calls:
+
+```typescript
+import { patchOpenAI } from 'risicare/openai';
+import OpenAI from 'openai';
+
+const openai = patchOpenAI(new OpenAI());
+// All chat.completions.create and embeddings calls are now traced.
+```
+
+### Supported Providers
+
+| Provider | Import |
+|----------|--------|
+| OpenAI | `risicare/openai` |
+| Anthropic | `risicare/anthropic` |
+| Vercel AI SDK | `risicare/vercel-ai` |
+
+## Decorators
+
+Structure your traces with agent identity and decision phases:
+
+```typescript
+import { agent, session, traceThink, traceDecide, traceAct } from 'risicare';
+
+const myAgent = agent({ name: 'planner', role: 'coordinator' }, async (input) => {
+  const analysis = await traceThink('analyze', async () => {
+    return await openai.chat.completions.create({ ... });
+  });
+
+  const decision = await traceDecide('choose-action', async () => {
+    return pickBestAction(analysis);
+  });
+
+  return await traceAct('execute', async () => {
+    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
+
+## Progressive Integration
+
+| 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 |
+
+## Requirements
+
+- Node.js >= 18.0.0
+- TypeScript >= 5.0 (optional, for type checking)
+
+## Links
+
+- [Documentation](https://risicare.ai/docs)
+- [Dashboard](https://app.risicare.ai)
+- [Python SDK](https://pypi.org/project/risicare/)