@coalex-ai/sdk 0.5.1 → 0.5.2
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.
- package/README.md +151 -0
- package/dist/index.d.ts +1 -1
- package/dist/index.d.ts.map +1 -1
- package/dist/index.js +1 -1
- package/dist/index.js.map +1 -1
- 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.d.ts
CHANGED
|
@@ -6,7 +6,7 @@ export { evaluate, KNOWN_METRICS } from "./evaluate.js";
|
|
|
6
6
|
export type { EvaluateOptions, EvaluationDecision } from "./evaluate.js";
|
|
7
7
|
export { resolve, VALID_DECISIONS } from "./resolve.js";
|
|
8
8
|
export type { ResolveOptions, ResolutionResult, MetricResult } from "./resolve.js";
|
|
9
|
-
export { autoInstrument, instrumentOpenAI, instrumentLangChain, instrumentAnthropic } from "./auto-instrument.js";
|
|
9
|
+
export { autoInstrument, autoInstrumentAsync, instrumentOpenAI, instrumentLangChain, instrumentAnthropic } from "./auto-instrument.js";
|
|
10
10
|
export type { AutoInstrumentOptions, InstrumentationStatus } from "./auto-instrument.js";
|
|
11
11
|
export declare function getConfig(): CoalexConfig;
|
|
12
12
|
export declare function getApiKey(): string;
|
package/dist/index.d.ts.map
CHANGED
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAMA,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAKhD,YAAY,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,EAAE,aAAa,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAChE,YAAY,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACzD,OAAO,EAAE,QAAQ,EAAE,aAAa,EAAE,MAAM,eAAe,CAAC;AACxD,YAAY,EAAE,eAAe,EAAE,kBAAkB,EAAE,MAAM,eAAe,CAAC;AACzE,OAAO,EAAE,OAAO,EAAE,eAAe,EAAE,MAAM,cAAc,CAAC;AACxD,YAAY,EAAE,cAAc,EAAE,gBAAgB,EAAE,YAAY,EAAE,MAAM,cAAc,CAAC;AACnF,OAAO,EAAE,cAAc,EAAE,mBAAmB,EAAE,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;AACvI,YAAY,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,sBAAsB,CAAC;AAKzF,wBAAgB,SAAS,IAAI,YAAY,CAKxC;AAED,wBAAgB,SAAS,IAAI,MAAM,CAKlC;AAED,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,gBAAgB,CAAC,EAAE,OAAO,CAAC;IAC3B,oBAAoB,CAAC,EAAE,OAAO,CAAC;CAChC;AAED,wBAAgB,QAAQ,CAAC,OAAO,CAAC,EAAE,eAAe,GAAG,IAAI,CA0BxD;AAED,0CAA0C;AAC1C,wBAAgB,gBAAgB,IAAI,IAAI,CAGvC"}
|
package/dist/index.js
CHANGED
|
@@ -9,7 +9,7 @@ import { CoalexAttributePropagator } from "./span-processor.js";
|
|
|
9
9
|
export { coalexContext, coalexContextSync } from "./context.js";
|
|
10
10
|
export { evaluate, KNOWN_METRICS } from "./evaluate.js";
|
|
11
11
|
export { resolve, VALID_DECISIONS } from "./resolve.js";
|
|
12
|
-
export { autoInstrument, instrumentOpenAI, instrumentLangChain, instrumentAnthropic } from "./auto-instrument.js";
|
|
12
|
+
export { autoInstrument, autoInstrumentAsync, instrumentOpenAI, instrumentLangChain, instrumentAnthropic } from "./auto-instrument.js";
|
|
13
13
|
let _config = null;
|
|
14
14
|
let _apiKey = null;
|
|
15
15
|
export function getConfig() {
|
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,gBAAgB,EAAE,mBAAmB,EAAE,mBAAmB,EAAE,MAAM,sBAAsB,CAAC;
|
|
1
|
+
{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}
|