@coalex-ai/sdk 0.5.2-beta.346 → 1.0.0-beta.377

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/README.md +151 -0
  2. package/dist/index.js +1 -1
  3. package/dist/index.js.map +1 -1
  4. package/package.json +1 -1
package/README.md ADDED
@@ -0,0 +1,151 @@
1
+ # @coalex-ai/sdk
2
+
3
+ TypeScript SDK for [Coalex](https://coalex.ai) — AI governance observability for enterprises in regulated markets.
4
+
5
+ Built on [OpenTelemetry](https://opentelemetry.io/). Ships as pure ESM.
6
+
7
+ ## Install
8
+
9
+ ```bash
10
+ npm install @coalex-ai/sdk
11
+ # or
12
+ pnpm add @coalex-ai/sdk
13
+ ```
14
+
15
+ ## Quick Start
16
+
17
+ ```typescript
18
+ import { register, autoInstrumentAsync, coalexContext, evaluate } from "@coalex-ai/sdk";
19
+
20
+ // 1. Initialize the SDK
21
+ register({
22
+ apiKey: process.env.COALEX_API_KEY,
23
+ serviceName: "my-agent",
24
+ });
25
+
26
+ // 2. Auto-instrument AI libraries (OpenAI, LangChain, Anthropic)
27
+ await autoInstrumentAsync();
28
+
29
+ // 3. Wrap agent invocations for tracing
30
+ const result = await coalexContext({ agentId: "support-agent" }, async () => {
31
+ // Your AI agent logic here
32
+ return await chain.invoke({ question: "..." });
33
+ });
34
+ ```
35
+
36
+ ## API
37
+
38
+ ### `register(options?)`
39
+
40
+ Initialize the SDK. Must be called before any other function.
41
+
42
+ ```typescript
43
+ register({
44
+ endpoint: "https://collect.coalex.ai", // default
45
+ apiKey: "your-api-key",
46
+ serviceName: "my-agent",
47
+ filterNonAiSpans: false, // filter out non-AI spans
48
+ suppressExportErrors: true, // suppress OTLP export errors (default)
49
+ });
50
+ ```
51
+
52
+ ### `autoInstrumentAsync(options?)`
53
+
54
+ Instrument AI libraries using dynamic `import()`. Use this in ESM projects.
55
+
56
+ ```typescript
57
+ const results = await autoInstrumentAsync();
58
+ // { openai: "success", langchain: "not_installed", anthropic: "success" }
59
+ ```
60
+
61
+ ### `autoInstrument(options?)`
62
+
63
+ Synchronous variant using `require()`. Use this in CommonJS projects.
64
+
65
+ ```typescript
66
+ const results = autoInstrument();
67
+ ```
68
+
69
+ Both accept an options object:
70
+
71
+ ```typescript
72
+ autoInstrumentAsync({
73
+ includeLibraries: ["openai", "anthropic"], // only these
74
+ excludeLibraries: ["langchain"], // skip these
75
+ tracerProvider: customProvider, // custom OTel provider
76
+ suppressErrors: true, // swallow errors (default)
77
+ });
78
+ ```
79
+
80
+ ### `instrumentOpenAI()` / `instrumentLangChain()` / `instrumentAnthropic()`
81
+
82
+ Convenience functions to instrument a single library.
83
+
84
+ ```typescript
85
+ instrumentOpenAI(); // returns boolean
86
+ ```
87
+
88
+ ### `coalexContext(options, fn)` / `coalexContextSync(options, fn)`
89
+
90
+ Wrap a function in a traced Coalex invocation span.
91
+
92
+ ```typescript
93
+ const result = await coalexContext(
94
+ { agentId: "my-agent", requestId: "req-123", version: "1.0" },
95
+ async () => {
96
+ // traced code
97
+ },
98
+ );
99
+ ```
100
+
101
+ ### `evaluate(options)`
102
+
103
+ Submit an AI output for evaluation. Returns the governance decision.
104
+
105
+ ```typescript
106
+ const decision = await evaluate({
107
+ traceId: "abc-123",
108
+ input: { question: "What is the policy?" },
109
+ output: { answer: "The policy states..." },
110
+ metrics: { answer: ["f1", "semantic_similarity"] },
111
+ });
112
+ // { status: "auto_approved" | "escalated" | "rejected", riskScore: 0.12, escalationId?: "..." }
113
+ ```
114
+
115
+ Available metrics: `f1`, `word_overlap`, `bleu`, `rouge_l`, `semantic_similarity`, `exact_match`, `levenshtein`, `contains`.
116
+
117
+ ### `resolve(options)`
118
+
119
+ Resolve an escalated evaluation.
120
+
121
+ ```typescript
122
+ const result = await resolve({
123
+ escalationId: "esc-456",
124
+ decision: "approved", // "approved" | "rejected" | "corrected"
125
+ reviewer: "analyst@company.com",
126
+ reason: "Output is accurate",
127
+ });
128
+ ```
129
+
130
+ ## Extension Spans
131
+
132
+ Import from `@coalex-ai/sdk/ext` for fine-grained tracing of RAG pipelines:
133
+
134
+ ```typescript
135
+ import { toolSpan, embeddingSpan, retrievalSpan, rerankerSpan, guardrailSpan } from "@coalex-ai/sdk/ext";
136
+ ```
137
+
138
+ - **`toolSpan`** — Trace tool/function calls
139
+ - **`embeddingSpan`** — Trace embedding generation
140
+ - **`retrievalSpan`** — Trace document retrieval
141
+ - **`rerankerSpan`** — Trace reranking steps
142
+ - **`guardrailSpan`** — Trace guardrail checks
143
+
144
+ ## Requirements
145
+
146
+ - Node.js 18+
147
+ - TypeScript 5.0+ (for type-checking)
148
+
149
+ ## License
150
+
151
+ Apache-2.0
package/dist/index.js CHANGED
@@ -25,7 +25,7 @@ export function getApiKey() {
25
25
  return _apiKey;
26
26
  }
27
27
  export function register(options) {
28
- const endpoint = options?.endpoint ?? "https://collect.coalex.ai";
28
+ const endpoint = options?.endpoint ?? "https://traces.azure.coalex.ai";
29
29
  const apiKey = options?.apiKey ?? "dev";
30
30
  const serviceName = options?.serviceName ?? "coalex-sdk-typescript";
31
31
  const filterNonAiSpans = options?.filterNonAiSpans ?? false;
package/dist/index.js.map CHANGED
@@ -1 +1 @@
1
- {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,0BAA0B,CAAC;AACpD,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,kBAAkB,EAAE,MAAM,+BAA+B,CAAC;AACnE,OAAO,EAAE,iBAAiB,EAAE,MAAM,yCAAyC,CAAC;AAC5E,OAAO,EAAE,iBAAiB,EAAE,MAAM,qCAAqC,CAAC;AAGxE,OAAO,EAAE,oBAAoB,EAAE,MAAM,oBAAoB,CAAC;AAC1D,OAAO,EAAE,qBAAqB,EAAE,MAAM,yBAAyB,CAAC;AAChE,OAAO,EAAE,yBAAyB,EAAE,MAAM,qBAAqB,CAAC;AAGhE,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAEhE,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AAExD,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AAExD,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AAGvI,IAAI,OAAO,GAAwB,IAAI,CAAC;AACxC,IAAI,OAAO,GAAkB,IAAI,CAAC;AAElC,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAED,MAAM,UAAU,SAAS;IACvB,IAAI,CAAC,OAAO,EAAE,CAAC;QACb,MAAM,IAAI,KAAK,CAAC,uDAAuD,CAAC,CAAC;IAC3E,CAAC;IACD,OAAO,OAAO,CAAC;AACjB,CAAC;AAUD,MAAM,UAAU,QAAQ,CAAC,OAAyB;IAChD,MAAM,QAAQ,GAAG,OAAO,EAAE,QAAQ,IAAI,2BAA2B,CAAC;IAClE,MAAM,MAAM,GAAG,OAAO,EAAE,MAAM,IAAI,KAAK,CAAC;IACxC,MAAM,WAAW,GAAG,OAAO,EAAE,WAAW,IAAI,uBAAuB,CAAC;IACpE,MAAM,gBAAgB,GAAG,OAAO,EAAE,gBAAgB,IAAI,KAAK,CAAC;IAC5D,MAAM,oBAAoB,GAAG,OAAO,EAAE,oBAAoB,IAAI,IAAI,CAAC;IAEnE,OAAO,GAAG,EAAE,QAAQ,EAAE,WAAW,EAAE,CAAC;IACpC,OAAO,GAAG,MAAM,CAAC;IAEjB,MAAM,QAAQ,GAAG,IAAI,QAAQ,CAAC,EAAE,CAAC,iBAAiB,CAAC,EAAE,WAAW,EAAE,CAAC,CAAC;IAEpE,MAAM,YAAY,GAAG,IAAI,iBAAiB,CAAC;QACzC,GAAG,EAAE,GAAG,QAAQ,YAAY;QAC5B,OAAO,EAAE,EAAE,aAAa,EAAE,UAAU,MAAM,EAAE,EAAE;KAC/C,CAAC,CAAC;IAEH,MAAM,YAAY,GAAG,IAAI,oBAAoB,CAAC,YAAY,EAAE,oBAAoB,CAAC,CAAC;IAClF,MAAM,aAAa,GAAG,gBAAgB;QACpC,CAAC,CAAC,IAAI,qBAAqB,CAAC,YAAY,CAAC;QACzC,CAAC,CAAC,YAAY,CAAC;IAEjB,MAAM,QAAQ,GAAG,IAAI,kBAAkB,CAAC,EAAE,QAAQ,EAAE,CAAC,CAAC;IACtD,QAAQ,CAAC,gBAAgB,CAAC,IAAI,yBAAyB,EAAE,CAAC,CAAC;IAC3D,QAAQ,CAAC,gBAAgB,CAAC,IAAI,kBAAkB,CAAC,aAAa,CAAC,CAAC,CAAC;IACjE,QAAQ,CAAC,QAAQ,EAAE,CAAC;AACtB,CAAC;AAED,0CAA0C;AAC1C,MAAM,UAAU,gBAAgB;IAC9B,OAAO,GAAG,IAAI,CAAC;IACf,OAAO,GAAG,IAAI,CAAC;AACjB,CAAC"}
1
+ {"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@coalex-ai/sdk",
3
- "version": "0.5.2-beta.346",
3
+ "version": "1.0.0-beta.377",
4
4
  "description": "Coalex TypeScript SDK for AI governance observability",
5
5
  "license": "Apache-2.0",
6
6
  "repository": {