effect-assistant 0.11.0 → 0.12.0

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/src/Assistant.ts CHANGED
@@ -20,10 +20,12 @@ import * as Context from "effect/Context"
20
20
  import * as Effect from "effect/Effect"
21
21
  import * as Filter from "effect/Filter"
22
22
  import * as Layer from "effect/Layer"
23
+ import type * as Option from "effect/Option"
23
24
  import * as Predicate from "effect/Predicate"
24
25
  import * as Schema from "effect/Schema"
25
- import type * as Scope from "effect/Scope"
26
+ import * as Scope from "effect/Scope"
26
27
  import * as Stream from "effect/Stream"
28
+ import type * as Tracer from "effect/Tracer"
27
29
  import { AssistantEngine } from "./AssistantEngine.ts"
28
30
  import * as AssistantEvent from "./AssistantEvent.ts"
29
31
  import type * as AssistantLoop from "./AssistantLoop.ts"
@@ -33,6 +35,7 @@ import * as Chats from "./Chats.ts"
33
35
  import type { CurrentChat } from "./CurrentChat.ts"
34
36
  import type * as Instructions from "./Instructions.ts"
35
37
  import * as AppEvents from "./internal/events.ts"
38
+ import * as Telemetry from "./internal/telemetry.ts"
36
39
  import * as Turns from "./internal/turns.ts"
37
40
  import type * as Specialist from "./Specialist.ts"
38
41
 
@@ -237,6 +240,29 @@ const toStream = <R, RE>(
237
240
  | Effect.Effect<Stream.Stream<AssistantLoop.Event, unknown, R>, unknown, RE>
238
241
  ): Stream.Stream<AssistantLoop.Event, unknown, R | RE> => (Effect.isEffect(result) ? Stream.unwrap(result) : result)
239
242
 
243
+ /**
244
+ * Sets the tracer that an assistant's turns and specialist runs record their spans with. Each
245
+ * turn's `invoke_agent` span is then the root of a trace on that tracer, with the turn's model
246
+ * calls and tool calls below it. By default they use the tracer of the fiber that runs them.
247
+ *
248
+ * Provide it to the assistant's layer to send the agent's work to its own backend, such as an LLM
249
+ * observability tool, while the rest of the app traces elsewhere.
250
+ *
251
+ * @example
252
+ * ```ts
253
+ * const AgentTracer = Layer.effect(
254
+ * Assistant.TurnTracer,
255
+ * OtlpTracer.make({ url: "https://llm-observability.example.com/v1/traces" }).pipe(Effect.map(Option.some))
256
+ * )
257
+ *
258
+ * const MyAssistantLive = MyAssistant.toLayer(handler).pipe(Layer.provide(AgentTracer))
259
+ * ```
260
+ *
261
+ * @category references
262
+ * @since 0.12.0
263
+ */
264
+ export const TurnTracer: Context.Reference<Option.Option<Tracer.Tracer>> = Telemetry.TurnTracer
265
+
240
266
  /**
241
267
  * Identifies an assistant's service in a context. Each assistant has its own identifier, keyed by
242
268
  * its name.
@@ -590,7 +616,11 @@ export const make = <
590
616
  return Layer.effect(
591
617
  Key,
592
618
  Effect.gen(function* () {
593
- const context = yield* Effect.context()
619
+ // Without the layer's scope: what a build or a turn sets up lives as long as the chat or the turn.
620
+ const context = yield* Effect.context().pipe(
621
+ Effect.map(Context.omit(Scope.Scope)),
622
+ Effect.map(Telemetry.withoutTracing)
623
+ )
594
624
 
595
625
  const registration = yield* Turns.register(definition, {
596
626
  // The build runs per chat activation, in the chat; here it only keeps the layer's services for it.
@@ -601,8 +631,8 @@ export const make = <
601
631
  const handler = Effect.isEffect(build) ? yield* Effect.provideService(build, ChatKey, chat) : build
602
632
 
603
633
  return (turn: Turn<any>) =>
604
- Stream.provideContext(toStream(handler(turn)), context).pipe(Stream.provideService(ChatKey, chat))
605
- }).pipe(Effect.provideContext(context), Effect.orDie)
634
+ Stream.provide(toStream(handler(turn)), context).pipe(Stream.provideService(ChatKey, chat))
635
+ }).pipe(Effect.provide(context), Effect.orDie)
606
636
  })
607
637
 
608
638
  yield* (yield* AssistantEngine).register(registration)
@@ -105,7 +105,8 @@ const notRegistered = (assistant: string) =>
105
105
  export const layerMemory: Layer.Layer<AssistantEngine, never, ChatLog> = Layer.effect(
106
106
  AssistantEngine,
107
107
  Effect.gen(function* () {
108
- const context = yield* Effect.context<ChatLog>()
108
+ // Without the layer's scope, so a chat's resources close with its entry.
109
+ const context = yield* Effect.context<ChatLog>().pipe(Effect.map(Context.omit(Scope.Scope)))
109
110
  const log = yield* ChatLog
110
111
  const registered = new Map<string, Turns.Registration>()
111
112
  // A chat's keep-alive: a hold on its entry, so it stays open while runs or turns work in the background.
@@ -311,7 +312,8 @@ const makeClusterClient = Effect.gen(function* () {
311
312
  export const layerCluster: Layer.Layer<AssistantEngine, never, ChatLog | Sharding.Sharding> = Layer.effect(
312
313
  AssistantEngine,
313
314
  Effect.gen(function* () {
314
- const context = yield* Effect.context<ChatLog | Sharding.Sharding>()
315
+ // Without the layer's scope, so a chat's resources close with its entity.
316
+ const context = yield* Effect.context<ChatLog | Sharding.Sharding>().pipe(Effect.map(Context.omit(Scope.Scope)))
315
317
  const sharding = yield* Sharding.Sharding
316
318
 
317
319
  const register = Effect.fnUntraced(function* (registration: Turns.Registration) {
package/src/Specialist.ts CHANGED
@@ -16,12 +16,13 @@ import * as Context from "effect/Context"
16
16
  import * as Effect from "effect/Effect"
17
17
  import * as Layer from "effect/Layer"
18
18
  import * as Schema from "effect/Schema"
19
- import type * as Scope from "effect/Scope"
19
+ import * as Scope from "effect/Scope"
20
20
  import * as Stream from "effect/Stream"
21
21
  import type * as AssistantLoop from "./AssistantLoop.ts"
22
22
  import type { ChatId } from "./ChatId.ts"
23
23
  import type { CurrentChat } from "./CurrentChat.ts"
24
24
  import type * as Instructions from "./Instructions.ts"
25
+ import * as Telemetry from "./internal/telemetry.ts"
25
26
  import type { RunId } from "./RunId.ts"
26
27
 
27
28
  const TypeId = "~effect-assistant/Specialist"
@@ -257,7 +258,11 @@ export const make = <const Name extends string>(
257
258
  return Layer.effect(
258
259
  Handler,
259
260
  Effect.gen(function* () {
260
- const context = yield* Effect.context()
261
+ // Without the layer's scope: what a build or a turn sets up lives as long as the chat or the turn.
262
+ const context = yield* Effect.context().pipe(
263
+ Effect.map(Context.omit(Scope.Scope)),
264
+ Effect.map(Telemetry.withoutTracing)
265
+ )
261
266
 
262
267
  return {
263
268
  // The build runs per chat activation, in the chat; here it only keeps the layer's
@@ -265,8 +270,8 @@ export const make = <const Name extends string>(
265
270
  open: Effect.gen(function* () {
266
271
  const handler = Effect.isEffect(build) ? yield* build : build
267
272
 
268
- return (turn: Turn) => Stream.provideContext(toStream(handler(turn)), context)
269
- }).pipe(Effect.provideContext(context), Effect.orDie)
273
+ return (turn: Turn) => Stream.provide(toStream(handler(turn)), context)
274
+ }).pipe(Effect.provide(context), Effect.orDie)
270
275
  }
271
276
  })
272
277
  )
@@ -254,6 +254,7 @@ export const make = Effect.fnUntraced(function* (options: {
254
254
  handle,
255
255
  specialists,
256
256
  model: registration.model,
257
+ tracer: registration.tracer,
257
258
  holding,
258
259
  report: Effect.fnUntraced(function* (finished) {
259
260
  yield* store(finished)
@@ -16,6 +16,7 @@ import * as Ref from "effect/Ref"
16
16
  import * as Schema from "effect/Schema"
17
17
  import * as Semaphore from "effect/Semaphore"
18
18
  import * as Stream from "effect/Stream"
19
+ import type * as Tracer from "effect/Tracer"
19
20
  import * as AssistantEvent from "../AssistantEvent.ts"
20
21
  import type * as AssistantLoop from "../AssistantLoop.ts"
21
22
  import * as Loop from "./loop.ts"
@@ -237,6 +238,7 @@ export const makeRunner = Effect.fnUntraced(function* (options: {
237
238
  readonly handler: RunHandler
238
239
  }>
239
240
  readonly model: Context.Context<LanguageModel.LanguageModel>
241
+ readonly tracer: Option.Option<Tracer.Tracer>
240
242
  // An interruption keeps the hold.
241
243
  readonly holding: (effect: Effect.Effect<void>) => Effect.Effect<void>
242
244
  readonly report: (finished: AssistantEvent.SpecialistFinished) => Effect.Effect<void>
@@ -264,6 +266,7 @@ export const makeRunner = Effect.fnUntraced(function* (options: {
264
266
  inbox: run.inbox,
265
267
  chatId: chat.chatId
266
268
  }).pipe(
269
+ Telemetry.onTracer(options.tracer),
267
270
  Effect.provideContext(Context.merge(options.model, services)),
268
271
  // Spawned from a turn, a run would inherit the turn's own tools: a run can't message the user.
269
272
  Effect.provideService(Loop.TurnTools, Option.none()),
@@ -1,6 +1,7 @@
1
1
  import * as Model from "effect/ai/Model"
2
2
  import * as Prompt from "effect/ai/Prompt"
3
3
  import * as Telemetry from "effect/ai/Telemetry"
4
+ import * as Context from "effect/Context"
4
5
  import * as Effect from "effect/Effect"
5
6
  import * as Option from "effect/Option"
6
7
  import * as References from "effect/References"
@@ -27,6 +28,21 @@ export const agentSpan = (name: string, options: { readonly chatId: string; read
27
28
  }
28
29
  })
29
30
 
31
+ /** @internal */
32
+ export const TurnTracer = Context.Reference<Option.Option<Tracer.Tracer>>("effect-assistant/Assistant/TurnTracer", {
33
+ defaultValue: Option.none
34
+ })
35
+
36
+ // A layer's context carries the tracer and span it was built with: a turn's own must not be replaced by them.
37
+ /** @internal */
38
+ export const withoutTracing = Context.omit(Tracer.ParentSpan, Tracer.Tracer)
39
+
40
+ /** @internal */
41
+ export const onTracer =
42
+ (tracer: Option.Option<Tracer.Tracer>) =>
43
+ <A, E, R>(self: Effect.Effect<A, E, R>): Effect.Effect<A, E, R> =>
44
+ Option.match(tracer, { onNone: () => self, onSome: (tracer) => self.pipe(Effect.withTracer(tracer)) })
45
+
30
46
  // None when tracing is off, or when the tracer is Effect's own, which exports nothing.
31
47
  /** @internal */
32
48
  export const currentTraceId: Effect.Effect<Option.Option<string>> = Effect.gen(function* () {
@@ -57,7 +73,10 @@ const annotateModelSpan = (
57
73
  name: Option.Option<string>,
58
74
  attributes: SpanAttributes | undefined
59
75
  ) => {
60
- span.attribute("gen_ai.prompt", toJsonText(Option.map(encodePrompt(prompt), (encoded) => encoded.content)))
76
+ span.attribute(
77
+ "gen_ai.prompt",
78
+ toJsonText(Option.getOrUndefined(Option.map(encodePrompt(prompt), (encoded) => encoded.content)))
79
+ )
61
80
  span.attribute("gen_ai.completion", toJsonText(Option.getOrUndefined(completionOf(response))))
62
81
 
63
82
  for (const [key, value] of Object.entries(attributes ?? {})) {
@@ -12,6 +12,7 @@ import * as Predicate from "effect/Predicate"
12
12
  import * as Ref from "effect/Ref"
13
13
  import * as Schema from "effect/Schema"
14
14
  import type * as Scope from "effect/Scope"
15
+ import type * as Tracer from "effect/Tracer"
15
16
  import * as Stream from "effect/Stream"
16
17
  import type * as Assistant from "../Assistant.ts"
17
18
  import type { ChatId } from "../ChatId.ts"
@@ -71,6 +72,7 @@ export interface TypedChat {
71
72
  export interface Registration {
72
73
  readonly definition: Definition
73
74
  readonly model: Context.Context<LanguageModel.LanguageModel>
75
+ readonly tracer: Option.Option<Tracer.Tracer>
74
76
  readonly open: (chat: TypedChat) => Effect.Effect<TurnHandler, never, Scope.Scope | CurrentChat>
75
77
  readonly specialists: ReadonlyArray<{
76
78
  readonly specialist: Specialist.Any
@@ -84,7 +86,8 @@ export const register = Effect.fnUntraced(function* (
84
86
  definition: Definition,
85
87
  options: { readonly open: Registration["open"] }
86
88
  ) {
87
- const model = yield* Effect.context<LanguageModel.LanguageModel>()
89
+ const model = yield* Effect.context<LanguageModel.LanguageModel>().pipe(Effect.map(Telemetry.withoutTracing))
90
+ const tracer = yield* Telemetry.TurnTracer
88
91
 
89
92
  const specialists = yield* Effect.forEach(
90
93
  definition.specialists,
@@ -109,6 +112,7 @@ export const register = Effect.fnUntraced(function* (
109
112
  const registration: Registration = {
110
113
  definition,
111
114
  model,
115
+ tracer,
112
116
  open: options.open,
113
117
  specialists,
114
118
  builtins
@@ -407,6 +411,7 @@ export const run = Effect.fnUntraced(
407
411
  Telemetry.agentSpan(options.registration.definition.name, {
408
412
  chatId: options.chat.chatId,
409
413
  root: true
410
- })
414
+ }),
415
+ Telemetry.onTracer(options.registration.tracer)
411
416
  )
412
417
  )