@aeye/core 0.1.0

package/dist/agent.js

@@ -0,0 +1,81 @@
+/**
+ * An Agent component that orchestrates complex workflows by composing other AI components.
+ * Agents can utilize tools, prompts, and other agents to accomplish sophisticated tasks.
+ *
+ * @template TContext - The context type needed for the agent's operation.
+ * @template TMetadata - The metadata type needed during execution/streaming.
+ * @template TName - The name of the agent, typed for inference in parent components.
+ * @template TInput - The input parameters type for the agent.
+ * @template TOutput - The output type for the agent.
+ * @template TRefs - References to other components that this agent depends on.
+ *
+ * @example
+ * const researchAgent = new Agent({
+ *   name: 'researcher',
+ *   description: 'Conducts research using multiple tools',
+ *   refs: [searchTool, summarizeTool, analyzePrompt],
+ *   call: async (input, [search, summarize, analyze], ctx) => {
+ *     const results = await search.run({ query: input.topic }, ctx);
+ *     const summary = await summarize.get({ text: results });
+ *     return analyze.get({ summary, topic: input.topic });
+ *   }
+ * });
+ */
+export class Agent {
+    input;
+    /**
+     * Creates a new Agent instance.
+     *
+     * @param input - The agent input configuration.
+     */
+    constructor(input) {
+        this.input = input;
+    }
+    get kind() {
+        return 'agent';
+    }
+    get name() {
+        return this.input.name;
+    }
+    get description() {
+        return this.input.description;
+    }
+    get refs() {
+        return this.input.refs;
+    }
+    /**
+     * Executes the agent with the provided context and input.
+     * If a custom runner is provided in the context, it will be used instead of direct execution.
+     *
+     * @param input - The input parameters for the agent.
+     * @param ctx - The execution context.
+     * @returns The output of the agent's operation.
+     */
+    run(...[inputMaybe, contextMaybe]) {
+        const input = (inputMaybe || {});
+        const ctx = (contextMaybe || {});
+        const agent = this;
+        return ctx.runner
+            ? ctx.runner(agent, input, ctx, (innerCtx) => this.input.call(input, this.input.refs, innerCtx))
+            : this.input.call(input, this.input.refs, ctx);
+    }
+    /**
+     * Determines whether the agent is applicable in the given context.
+     * By default, checks if any of its referenced components are applicable.
+     *
+     * @param ctx - The context to check applicability against.
+     * @returns A promise that resolves to true if the agent is applicable, false otherwise.
+     */
+    async applicable(...[contextMaybe]) {
+        const ctx = (contextMaybe || {});
+        if (this.input.applicable) {
+            return this.input.applicable(ctx);
+        }
+        // If there are no refs, the agent is self-contained and applicable
+        if (this.refs.length === 0) {
+            return true;
+        }
+        return await Promise.all(this.refs.map(ref => ref.applicable(ctx))).then(results => results.some(r => r));
+    }
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAwCA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AACH,MAAM,OAAO,KAAK;IAeP;IANT;;;;OAIG;IACH,YACS,KAAqE;QAArE,UAAK,GAAL,KAAK,CAAgE;IAC1E,CAAC;IAEL,IAAI,IAAI;QACN,OAAO,OAAO,CAAC;IACjB,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED,IAAI,WAAW;QACb,OAAO,IAAI,CAAC,KAAK,CAAC,WAAW,CAAC;IAChC,CAAC;IAED,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC;IACzB,CAAC;IAED;;;;;;;OAOG;IACH,GAAG,CAID,GAAG,CAAC,UAAU,EAAE,YAAY,CAAyC;QACrE,MAAM,KAAK,GAAG,CAAC,UAAU,IAAI,EAAE,CAAW,CAAC;QAC3C,MAAM,GAAG,GAAG,CAAC,YAAY,IAAI,EAAE,CAAiC,CAAC;QACjE,MAAM,KAAK,GAAG,IAAqE,CAAC;QAEpF,OAAO,GAAG,CAAC,MAAM;YACf,CAAC,CAAC,GAAG,CAAC,MAAM,CAAC,KAAK,EAAE,KAAK,EAAE,GAAG,EAAE,CAAC,QAAQ,EAAE,EAAE,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC;YAChG,CAAC,CAAC,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,KAAK,EAAE,IAAI,CAAC,KAAK,CAAC,IAAI,EAAE,GAAG,CAAC,CAAC;IACnD,CAAC;IAED;;;;;;OAMG;IACH,KAAK,CAAC,UAAU,CAId,GAAG,CAAC,YAAY,CAAiC;QACjD,MAAM,GAAG,GAAG,CAAC,YAAY,IAAI,EAAE,CAAiC,CAAC;QAEjE,IAAI,IAAI,CAAC,KAAK,CAAC,UAAU,EAAE,CAAC;YAC1B,OAAO,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC;QACpC,CAAC;QAED,mEAAmE;QACnE,IAAI,IAAI,CAAC,IAAI,CAAC,MAAM,KAAK,CAAC,EAAE,CAAC;YAC3B,OAAO,IAAI,CAAC;QACd,CAAC;QAED,OAAO,MAAM,OAAO,CAAC,GAAG,CAAC,IAAI,CAAC,IAAI,CAAC,GAAG,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,UAAU,CAAC,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,CAAC,OAAO,CAAC,EAAE,CAAC,OAAO,CAAC,IAAI,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,CAAC,CAAC;IAC5G,CAAC;CAEF"}

package/dist/common.d.ts

@@ -0,0 +1,161 @@
+import { Chunk, Model, ModelInput, Response, Runner, Usage, Events } from "./types";
+/**
+ * A flexible function type that can be:
+ * - A direct value of type R
+ * - A function that takes arguments A and returns R or Promise<R>
+ * - A Promise that resolves to R
+ */
+export type Fn<R, A extends [any?, ...any[]] = []> = R | ((...args: A) => (R | Promise<R>)) | Promise<R>;
+/**
+ * Computes the resulting type R from a flexible function type Fn.
+ */
+export type FnResult<R> = R extends Promise<infer U> ? U : R extends (...args: any[]) => infer V ? V extends Promise<infer W> ? W : V : R;
+/**
+ * Retrieves the argument types A from a flexible function type Fn.
+ */
+export type FnArgs<F, Assumed = never> = F extends (...args: infer A) => any ? A : Assumed;
+/**
+ * Resolves a flexible function type into its standardized async function form.
+ */
+export type FnResolved<F extends Fn<any, any> | undefined> = F extends undefined ? () => Promise<undefined> : F extends Fn<infer R, infer A> ? (...args: A) => Promise<R> : never;
+/**
+ * Converts a flexible function type into a standardized async function.
+ * Handles values, functions, and promises uniformly by wrapping them in async functions.
+ *
+ * @param fn - The flexible function type to convert.
+ * @param reprocess - Optional function to transform the resolved value.
+ * @returns An async function that takes the same arguments and returns a Promise of the resolved type.
+ * @example
+ * const fn1 = resolveFn(42); // () => Promise<42>
+ * const fn2 = resolveFn(() => 'hello'); // () => Promise<'hello'>
+ * const fn3 = resolveFn(Promise.resolve(10)); // () => Promise<10>
+ */
+export declare function resolveFn<R, A extends [any?, ...any[]] = []>(fn: undefined): ((...args: A) => Promise<undefined>);
+export declare function resolveFn<R, A extends [any?, ...any[]] = []>(fn: Fn<R, A>): ((...args: A) => Promise<R>);
+export declare function resolveFn<R, A extends [any?, ...any[]] = [], R2 = R>(fn: Fn<R, A>, reprocess: (r: R) => R2): ((...args: A) => Promise<R2>);
+/**
+ * Checks if a promise has settled (either fulfilled or rejected).
+ *
+ * @param p - The promise to check.
+ * @returns A promise that resolves to true if settled, false otherwise.
+ */
+export declare function isSettled(p: Promise<any>): Promise<boolean>;
+/**
+ * Type guard to check if a value is a Promise.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is a Promise, false otherwise.
+ */
+export declare function isPromise<T = any>(value: any): value is Promise<T>;
+/**
+ * Type guard to check if a value is an AsyncGenerator.
+ *
+ * @param value - The value to check.
+ * @returns True if the value is an AsyncGenerator, false otherwise.
+ */
+export declare function isAsyncGenerator(value: any): value is AsyncGenerator<any, any, any>;
+/**
+ * Yields promises as they settle (either fulfill or reject), maintaining their original indices.
+ * Useful for processing multiple async operations as soon as each one completes.
+ *
+ * @param promises - Array of promises to yield as they settle.
+ * @returns An async generator yielding objects with the settled promise and its index.
+ * @example
+ * const promises = [delay(100), delay(50), delay(200)];
+ * for await (const { result, index } of yieldAll(promises)) {
+ *   console.log(`Promise ${index} settled`);
+ *   const value = await result;
+ * }
+ */
+export declare function yieldAll<T>(promises: Promise<T>[]): AsyncGenerator<{
+    result: Promise<T>;
+    index: number;
+}>;
+/**
+ * Resolves an output value from various input types.
+ * Handles promises, raw values, and AsyncGenerators uniformly.
+ * These are all common return types of AI components.
+ *
+ * @param input - The value to resolve (can be a value, Promise, or AsyncGenerator).
+ * @returns A promise that resolves to the final value.
+ * @example
+ * await resolve(42); // 42
+ * await resolve(Promise.resolve('hello')); // 'hello'
+ * await resolve(asyncGenerator()); // final return value
+ */
+export declare function resolve(input: any): Promise<any>;
+/**
+ * Consumes all values from an AsyncGenerator and returns them as an array.
+ *
+ * @param gen - The AsyncGenerator to consume.
+ * @returns An array of all values yielded by the generator.
+ */
+export declare function consumeAll<E>(gen: AsyncGenerator<E, any, any>): Promise<E[]>;
+/**
+ * Resolves the type R from a value passed to `resolve`.
+ */
+export type Resolved<T> = T extends Promise<infer U> ? Resolved<U> : T extends AsyncGenerator<any, infer U, any> ? Resolved<U> : T;
+/**
+ * Accumulates usage statistics by adding values from one Usage object to another.
+ * Handles the nested structure matching ModelPricing.
+ *
+ * @param target - The target Usage object to accumulate into.
+ * @param add - The Usage object to add from.
+ * @returns
+ */
+export declare function accumulateUsage(target: Usage, add?: Usage): void;
+/**
+ * Calculate total input tokens from a Usage object.
+ * Includes tokens from text, audio, image, reasoning input, and embeddings.
+ *
+ * @param usage - The Usage object to calculate input tokens from
+ * @returns Total input tokens
+ */
+export declare function getInputTokens(usage?: Usage): number;
+/**
+ * Calculate total output tokens from a Usage object.
+ * Includes tokens from text, audio, and reasoning output.
+ * Note: image.output represents generated images (not tokens), so it's excluded.
+ *
+ * @param usage - The Usage object to calculate output tokens from
+ * @returns Total output tokens
+ */
+export declare function getOutputTokens(usage?: Usage): number;
+/**
+ * Calculate total tokens from a Usage object.
+ * Includes all tokens: input, output, cached from all modalities.
+ * Note: image.output represents generated images (not tokens), so it's excluded.
+ *
+ * @param usage - The Usage object to calculate total tokens from
+ * @returns Total tokens
+ */
+export declare function getTotalTokens(usage?: Usage): number;
+/**
+ * Gets a Model object from either a string ID or a ModelInput object.
+ *
+ * @param input - The model identifier or ModelInput object.
+ * @returns
+ */
+export declare function getModel(input: ModelInput): Model;
+export declare function getModel(input: ModelInput | undefined): Model | undefined;
+/**
+ * Converts a series of chunks into a Response object.
+ *
+ * @param chunks - The array of Chunk objects to convert.
+ * @returns The aggregated Response object.
+ */
+export declare function getResponseFromChunks(chunks: Chunk[]): Response;
+/**
+ * Converts a Response object into an array of Chunk objects.
+ *
+ * @param response - The response to convert.
+ * @returns The built chunks from the response.
+ */
+export declare function getChunksFromResponse(response: Response): Chunk[];
+/**
+ * Creates a runner that emits events during component execution.
+ *
+ * @param events
+ * @returns
+ */ export declare function withEvents<TRoot extends AnyComponent>(events: Events<TRoot>): Runner;
+//# sourceMappingURL=common.d.ts.map

package/dist/common.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../src/common.ts"],"names":[],"mappings":"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"}