elsium-ai 0.2.0 → 0.2.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.
Files changed (2) hide show
  1. package/README.md +270 -59
  2. package/package.json +16 -12
package/README.md CHANGED
@@ -1,20 +1,9 @@
1
- <p align="center">
2
- <a href="https://github.com/elsium-ai/elsium-ai" target="blank"><img src="https://raw.githubusercontent.com/elsium-ai/elsium-ai/main/assets/logo.png" width="320" alt="ElsiumAI Logo" /></a>
3
- </p>
4
- <h3 align="center">Reliability. Governance. Reproducible AI.</h3>
5
- <p align="center">The TypeScript framework for AI systems you can trust in production.</p>
6
- <p align="center">
7
- <a href="https://github.com/elsium-ai/elsium-ai/actions"><img src="https://github.com/elsium-ai/elsium-ai/workflows/CI/badge.svg" alt="CI"></a>
8
- <a href="https://github.com/elsium-ai/elsium-ai/blob/main/LICENSE"><img src="https://img.shields.io/badge/license-MIT-blue.svg" alt="License"></a>
9
- <a href="https://www.npmjs.com/package/elsium-ai"><img src="https://img.shields.io/npm/v/elsium-ai.svg" alt="npm"></a>
10
- </p>
1
+ # elsium-ai
11
2
 
12
- ---
3
+ Single import for the entire ElsiumAI framework.
13
4
 
14
- > **AI systems must fail predictably.**
15
- > **AI systems must be auditable.**
16
- > **AI systems must be reproducible.**
17
- > **AI systems must be governed by policy, not hope.**
5
+ [![npm](https://img.shields.io/npm/v/elsium-ai.svg)](https://www.npmjs.com/package/elsium-ai)
6
+ [![License](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/elsium-ai/elsium-ai/blob/main/LICENSE)
18
7
 
19
8
  ---
20
9
 
@@ -22,72 +11,294 @@
22
11
 
23
12
  ```bash
24
13
  npm install elsium-ai
25
- # or
26
- bun add elsium-ai
27
14
  ```
28
15
 
29
- This umbrella package re-exports all ElsiumAI modules. You can also install individual packages for smaller bundles.
16
+ ---
17
+
18
+ ## Why use this package?
19
+
20
+ `elsium-ai` is the umbrella package that re-exports every public API from all ElsiumAI sub-packages. Instead of installing and importing from many individual packages, you can import everything from a single entry point.
30
21
 
31
- ## Quick Start
22
+ **Before** -- importing from individual sub-packages:
32
23
 
33
24
  ```typescript
34
- import { gateway } from 'elsium-ai'
35
- import { defineAgent } from 'elsium-ai'
36
- import { env } from 'elsium-ai'
25
+ import { env } from '@elsium-ai/core'
26
+ import { gateway } from '@elsium-ai/gateway'
27
+ import { defineAgent } from '@elsium-ai/agents'
28
+ ```
29
+
30
+ **After** -- importing from the umbrella package:
31
+
32
+ ```typescript
33
+ import { env, gateway, defineAgent } from 'elsium-ai'
34
+ ```
35
+
36
+ Same APIs, one dependency, one import path.
37
+
38
+ ---
39
+
40
+ ## What's Included
41
+
42
+ Every value and type listed below is available directly from `'elsium-ai'`.
43
+
44
+ ### `@elsium-ai/core`
45
+
46
+ | Values | Types |
47
+ |--------|-------|
48
+ | `ElsiumError` | `Role` |
49
+ | `ok` | `ContentPart` |
50
+ | `err` | `TextContent` |
51
+ | `isOk` | `ImageContent` |
52
+ | `isErr` | `Message` |
53
+ | `unwrap` | `ToolCall` |
54
+ | `unwrapOr` | `ToolResult` |
55
+ | `tryCatch` | `TokenUsage` |
56
+ | `tryCatchSync` | `CostBreakdown` |
57
+ | `createStream` | `StopReason` |
58
+ | `createLogger` | `LLMResponse` |
59
+ | `env` | `StreamEvent` |
60
+ | `envNumber` | `XRayData` |
61
+ | `envBool` | `StreamCheckpoint` |
62
+ | `generateId` | `ProviderConfig` |
63
+ | `generateTraceId` | `CompletionRequest` |
64
+ | `extractText` | `ToolDefinition` |
65
+ | `sleep` | `Middleware` |
66
+ | `retry` | `Result` |
67
+ | | `Ok` |
68
+ | | `Err` |
69
+ | | `ElsiumStream` |
70
+ | | `ResilientStreamOptions` |
71
+ | | `LogLevel` |
72
+ | | `Logger` |
73
+ | | `ErrorCode` |
74
+
75
+ ### `@elsium-ai/gateway`
76
+
77
+ | Values | Types |
78
+ |--------|-------|
79
+ | `gateway` | `LLMProvider` |
80
+ | `registerProviderFactory` | `ProviderFactory` |
81
+ | `calculateCost` | `Gateway` |
82
+ | `registerPricing` | `GatewayConfig` |
83
+ | `composeMiddleware` | `XRayStore` |
84
+ | `loggingMiddleware` | `ProviderMeshConfig` |
85
+ | `costTrackingMiddleware` | `ProviderEntry` |
86
+ | `xrayMiddleware` | `RoutingStrategy` |
87
+ | `createAnthropicProvider` | `ProviderMesh` |
88
+ | `createOpenAIProvider` | `SecurityMiddlewareConfig` |
89
+ | `createGoogleProvider` | `SecurityViolation` |
90
+ | `createProviderMesh` | `SecurityResult` |
91
+ | `securityMiddleware` | |
92
+ | `detectPromptInjection` | |
93
+ | `detectJailbreak` | |
94
+ | `redactSecrets` | |
95
+ | `checkBlockedPatterns` | |
96
+
97
+ ### `@elsium-ai/agents`
98
+
99
+ | Values | Types |
100
+ |--------|-------|
101
+ | `defineAgent` | `Agent` |
102
+ | `runSequential` | `AgentDependencies` |
103
+ | `runParallel` | `AgentConfig` |
104
+ | `runSupervisor` | `AgentResult` |
105
+ | `createMemory` | `AgentRunOptions` |
106
+ | `createSemanticValidator` | `GuardrailConfig` |
107
+ | `createAgentSecurity` | `AgentHooks` |
108
+ | `createConfidenceScorer` | `Memory` |
109
+ | `executeStateMachine` | `MemoryConfig` |
110
+ | | `SemanticGuardrailConfig` |
111
+ | | `SemanticCheck` |
112
+ | | `SemanticCheckResult` |
113
+ | | `SemanticValidationResult` |
114
+ | | `SemanticValidator` |
115
+ | | `AgentSecurityConfig` |
116
+ | | `AgentSecurityResult` |
117
+ | | `ConfidenceConfig` |
118
+ | | `ConfidenceResult` |
119
+ | | `StateDefinition` |
120
+ | | `StateHistoryEntry` |
121
+ | | `StateMachineResult` |
122
+
123
+ ### `@elsium-ai/tools`
124
+
125
+ | Values | Types |
126
+ |--------|-------|
127
+ | `defineTool` | `Tool` |
128
+ | `createToolkit` | `ToolConfig` |
129
+ | `httpFetchTool` | `ToolContext` |
130
+ | `calculatorTool` | `ToolExecutionResult` |
131
+ | `jsonParseTool` | `Toolkit` |
132
+ | `currentTimeTool` | |
133
+ | `formatToolResult` | |
134
+ | `formatToolResultAsText` | |
135
+
136
+ ### `@elsium-ai/rag`
137
+
138
+ | Values | Types |
139
+ |--------|-------|
140
+ | `rag` | `RAGPipeline` |
141
+ | `createInMemoryStore` | `RAGPipelineConfig` |
142
+ | `createOpenAIEmbeddings` | `IngestResult` |
143
+ | `createMockEmbeddings` | `Document` |
144
+ | | `Chunk` |
145
+ | | `EmbeddedChunk` |
146
+ | | `RetrievalResult` |
147
+ | | `QueryOptions` |
148
+ | | `EmbeddingProvider` |
149
+ | | `VectorStore` |
150
+
151
+ ### `@elsium-ai/workflows`
37
152
 
153
+ | Values | Types |
154
+ |--------|-------|
155
+ | `defineWorkflow` | `Workflow` |
156
+ | `defineParallelWorkflow` | `WorkflowConfig` |
157
+ | `defineBranchWorkflow` | `WorkflowResult` |
158
+ | `step` | `WorkflowRunOptions` |
159
+ | | `StepConfig` |
160
+ | | `StepContext` |
161
+ | | `StepResult` |
162
+
163
+ ### `@elsium-ai/observe`
164
+
165
+ | Values | Types |
166
+ |--------|-------|
167
+ | `observe` | `Tracer` |
168
+ | `createSpan` | `TracerConfig` |
169
+ | `createMetrics` | `TracerExporter` |
170
+ | `createCostEngine` | `CostReport` |
171
+ | `toOTelSpan` | `Span` |
172
+ | `toOTelExportRequest` | `SpanData` |
173
+ | `toTraceparent` | `SpanKind` |
174
+ | `parseTraceparent` | `SpanStatus` |
175
+ | `injectTraceContext` | `MetricsCollector` |
176
+ | `extractTraceContext` | `MetricEntry` |
177
+ | `createOTLPExporter` | `CostEngine` |
178
+ | | `CostEngineConfig` |
179
+ | | `CostAlert` |
180
+ | | `CostDimension` |
181
+ | | `CostIntelligenceReport` |
182
+ | | `ModelSuggestion` |
183
+ | | `OTelSpan` |
184
+ | | `OTelExportRequest` |
185
+ | | `TraceContext` |
186
+ | | `OTLPExporterConfig` |
187
+
188
+ ### `@elsium-ai/app`
189
+
190
+ | Values | Types |
191
+ |--------|-------|
192
+ | `createApp` | `AppConfig` |
193
+ | | `ServerConfig` |
194
+ | | `CorsConfig` |
195
+ | | `AuthConfig` |
196
+ | | `RateLimitConfig` |
197
+
198
+ ### `@elsium-ai/mcp`
199
+
200
+ | Values | Types |
201
+ |--------|-------|
202
+ | `createMCPClient` | `MCPClient` |
203
+ | `createMCPServer` | `MCPClientConfig` |
204
+ | | `MCPToolInfo` |
205
+ | | `MCPServer` |
206
+ | | `MCPServerConfig` |
207
+
208
+ ### `@elsium-ai/testing`
209
+
210
+ | Values | Types |
211
+ |--------|-------|
212
+ | `mockProvider` | `MockProviderOptions` |
213
+ | `createFixture` | `MockResponseConfig` |
214
+ | `loadFixture` | `MockProvider` |
215
+ | `createRecorder` | `EvalSuiteConfig` |
216
+ | `runEvalSuite` | `EvalCase` |
217
+ | `formatEvalReport` | `EvalCriterion` |
218
+ | `createSnapshotStore` | `EvalResult` |
219
+ | `createPromptRegistry` | `EvalSuiteResult` |
220
+ | `definePrompt` | `LLMJudge` |
221
+ | `createRegressionSuite` | `SnapshotStore` |
222
+ | `createReplayRecorder` | `PromptDefinition` |
223
+ | `createReplayPlayer` | `PromptDiff` |
224
+ | | `PromptRegistry` |
225
+ | | `RegressionBaseline` |
226
+ | | `RegressionResult` |
227
+ | | `RegressionDetail` |
228
+ | | `RegressionSuite` |
229
+ | | `ReplayEntry` |
230
+ | | `ReplayRecorder` |
231
+ | | `ReplayPlayer` |
232
+
233
+ ---
234
+
235
+ ## Quick Example
236
+
237
+ ```typescript
238
+ import {
239
+ env,
240
+ gateway,
241
+ defineAgent,
242
+ defineTool,
243
+ observe,
244
+ createCostEngine,
245
+ } from 'elsium-ai'
246
+ import { z } from 'zod'
247
+
248
+ // Set up observability
249
+ const tracer = observe({ serviceName: 'my-app' })
250
+ const costEngine = createCostEngine({ budget: { daily: 10.0 } })
251
+
252
+ // Create a gateway to an LLM provider
38
253
  const llm = gateway({
39
254
  provider: 'anthropic',
40
255
  model: 'claude-sonnet-4-6',
41
256
  apiKey: env('ANTHROPIC_API_KEY'),
42
257
  })
43
258
 
259
+ // Define a tool
260
+ const weatherTool = defineTool({
261
+ name: 'get_weather',
262
+ description: 'Get current weather for a city',
263
+ parameters: z.object({ city: z.string() }),
264
+ execute: async ({ city }) => ({ temp: 72, city }),
265
+ })
266
+
267
+ // Define an agent with the tool
44
268
  const agent = defineAgent(
45
- { name: 'assistant', system: 'You are a helpful assistant.' },
269
+ {
270
+ name: 'assistant',
271
+ system: 'You are a helpful assistant.',
272
+ tools: [weatherTool],
273
+ },
46
274
  { complete: (req) => llm.complete(req) },
47
275
  )
48
276
 
49
- const result = await agent.run('What is TypeScript?')
277
+ // Run the agent
278
+ const result = await agent.run('What is the weather in Paris?')
279
+ console.log(result.output)
50
280
  ```
51
281
 
52
- ## Three Pillars
53
-
54
- | Pillar | The guarantee |
55
- |--------|--------------|
56
- | **Reliability** | Your system stays up when providers break — circuit breakers, bulkhead isolation, request dedup, graceful shutdown |
57
- | **Governance** | You control who does what, and you can prove it — policy engine, RBAC, approval gates, hash-chained audit trail |
58
- | **Reproducible AI** | Tools to measure, pin, and reproduce AI outputs — seed propagation, output pinning, provenance tracking, determinism assertions |
59
-
60
- ## Packages
61
-
62
- | Package | Description |
63
- |---------|-------------|
64
- | [`@elsium-ai/core`](https://www.npmjs.com/package/@elsium-ai/core) | Types, errors, streaming, circuit breaker, dedup, policy engine, shutdown |
65
- | [`@elsium-ai/gateway`](https://www.npmjs.com/package/@elsium-ai/gateway) | Multi-provider gateway, X-Ray, provider mesh, bulkhead, PII detection |
66
- | [`@elsium-ai/agents`](https://www.npmjs.com/package/@elsium-ai/agents) | Agents, memory, guardrails, approval gates, multi-agent |
67
- | [`@elsium-ai/tools`](https://www.npmjs.com/package/@elsium-ai/tools) | Tool definitions with Zod validation |
68
- | [`@elsium-ai/rag`](https://www.npmjs.com/package/@elsium-ai/rag) | Document loading, chunking, embeddings, vector search |
69
- | [`@elsium-ai/workflows`](https://www.npmjs.com/package/@elsium-ai/workflows) | Sequential, parallel, and branching workflows |
70
- | [`@elsium-ai/observe`](https://www.npmjs.com/package/@elsium-ai/observe) | Tracing, cost intelligence, audit trail, provenance tracking |
71
- | [`@elsium-ai/mcp`](https://www.npmjs.com/package/@elsium-ai/mcp) | Bidirectional MCP client and server |
72
- | [`@elsium-ai/app`](https://www.npmjs.com/package/@elsium-ai/app) | HTTP server, CORS, auth, rate limiting, RBAC |
73
- | [`@elsium-ai/testing`](https://www.npmjs.com/package/@elsium-ai/testing) | Mocks, evals, pinning, determinism assertions, prompt versioning |
74
- | [`@elsium-ai/cli`](https://www.npmjs.com/package/@elsium-ai/cli) | Scaffolding, dev server, X-Ray inspection |
75
-
76
- ## Performance
77
-
78
- Measured with zero-latency mock provider to isolate framework cost.
282
+ ---
79
283
 
80
- | Metric | P50 | P95 | Conditions |
81
- |---|:---:|:---:|---|
82
- | Core completion path | 2.3us | 5.5us | Agent, no middleware |
83
- | Full governance stack | 6.2us | 9.5us | Security + audit + policy + cost + xray + logging |
84
- | Under concurrency | 5.0us | 6.4us | 100 parallel requests, full stack |
284
+ ## Individual Packages
85
285
 
86
- Framework cost contribution: <0.01% of total request time.
286
+ For full API documentation, see each sub-package README.
87
287
 
88
- ## Documentation
288
+ | Package | npm | Description |
289
+ |---------|-----|-------------|
290
+ | `@elsium-ai/core` | [npm](https://www.npmjs.com/package/@elsium-ai/core) | Types, errors, result pattern, streaming, logger, config utilities |
291
+ | `@elsium-ai/gateway` | [npm](https://www.npmjs.com/package/@elsium-ai/gateway) | Multi-provider LLM gateway, middleware, provider mesh, security |
292
+ | `@elsium-ai/agents` | [npm](https://www.npmjs.com/package/@elsium-ai/agents) | Agent definitions, memory, guardrails, multi-agent orchestration |
293
+ | `@elsium-ai/tools` | [npm](https://www.npmjs.com/package/@elsium-ai/tools) | Tool definitions with Zod validation, built-in tools |
294
+ | `@elsium-ai/rag` | [npm](https://www.npmjs.com/package/@elsium-ai/rag) | Document ingestion, chunking, embeddings, vector search |
295
+ | `@elsium-ai/workflows` | [npm](https://www.npmjs.com/package/@elsium-ai/workflows) | Sequential, parallel, and branching workflow definitions |
296
+ | `@elsium-ai/observe` | [npm](https://www.npmjs.com/package/@elsium-ai/observe) | Tracing, metrics, cost intelligence, OpenTelemetry export |
297
+ | `@elsium-ai/app` | [npm](https://www.npmjs.com/package/@elsium-ai/app) | HTTP server with CORS, auth, and rate limiting |
298
+ | `@elsium-ai/mcp` | [npm](https://www.npmjs.com/package/@elsium-ai/mcp) | Model Context Protocol client and server |
299
+ | `@elsium-ai/testing` | [npm](https://www.npmjs.com/package/@elsium-ai/testing) | Mocks, fixtures, evals, snapshot testing, prompt versioning, replay |
89
300
 
90
- Full documentation, architecture diagrams, and examples at [github.com/elsium-ai/elsium-ai](https://github.com/elsium-ai/elsium-ai).
301
+ ---
91
302
 
92
303
  ## License
93
304
 
package/package.json CHANGED
@@ -1,12 +1,12 @@
1
1
  {
2
2
  "name": "elsium-ai",
3
- "version": "0.2.0",
3
+ "version": "0.2.2",
4
4
  "description": "ElsiumAI — A high-performance, TypeScript-first AI framework",
5
5
  "license": "MIT",
6
6
  "author": "Eric Utrera <ebutrera9103@gmail.com>",
7
7
  "repository": {
8
8
  "type": "git",
9
- "url": "https://github.com/elsium-ai/elsium-ai",
9
+ "url": "git+https://github.com/elsium-ai/elsium-ai.git",
10
10
  "directory": "packages/elsium-ai"
11
11
  },
12
12
  "type": "module",
@@ -25,18 +25,22 @@
25
25
  "build": "bun build ./src/index.ts --outdir ./dist --target node && bun x tsc -p tsconfig.build.json --emitDeclarationOnly"
26
26
  },
27
27
  "dependencies": {
28
- "@elsium-ai/core": "workspace:*",
29
- "@elsium-ai/gateway": "workspace:*",
30
- "@elsium-ai/agents": "workspace:*",
31
- "@elsium-ai/tools": "workspace:*",
32
- "@elsium-ai/rag": "workspace:*",
33
- "@elsium-ai/workflows": "workspace:*",
34
- "@elsium-ai/observe": "workspace:*",
35
- "@elsium-ai/app": "workspace:*",
36
- "@elsium-ai/testing": "workspace:*",
37
- "@elsium-ai/mcp": "workspace:*"
28
+ "@elsium-ai/core": "^0.2.2",
29
+ "@elsium-ai/gateway": "^0.2.2",
30
+ "@elsium-ai/agents": "^0.2.2",
31
+ "@elsium-ai/tools": "^0.2.2",
32
+ "@elsium-ai/rag": "^0.2.2",
33
+ "@elsium-ai/workflows": "^0.2.2",
34
+ "@elsium-ai/observe": "^0.2.2",
35
+ "@elsium-ai/app": "^0.2.2",
36
+ "@elsium-ai/testing": "^0.2.2",
37
+ "@elsium-ai/mcp": "^0.2.2"
38
38
  },
39
39
  "devDependencies": {
40
40
  "typescript": "^5.7.0"
41
+ },
42
+ "publishConfig": {
43
+ "registry": "https://registry.npmjs.org",
44
+ "access": "public"
41
45
  }
42
46
  }