More ergonomic typing on decorators

Andrei Bratu · Andrei Bratu · commit 342f0cb2a70c · 2025-04-22T19:43:19.000+03:00
diff --git a/src/decorators/flow.ts b/src/decorators/flow.ts
@@ -15,32 +15,14 @@ import {
 export function flowUtilityFactory<I, O>(
     client: HumanloopClient,
     opentelemetryTracer: Tracer,
-    callable: (
-        args: I extends Record<string, unknown> & {
-            messages?: ChatMessage[];
-        }
-            ? I
-            : never,
-    ) => O,
+    callable: (args: I) => O,
     path: string,
     attributes?: Record<string, unknown>,
-): (args: I) => Promise<O | undefined> & {
-    file: {
-        type: string;
-        version: { attributes?: Record<string, unknown> };
-        callable: (args: I) => Promise<O | undefined>;
-    };
-} {
+) {
     const flowKernel = { attributes: attributes || {} };
     const fileType = "flow";
 
-    const wrappedFunction = async (
-        inputs: I extends Record<string, unknown> & {
-            messages?: ChatMessage[];
-        }
-            ? I
-            : never,
-    ) => {
+    const wrappedFunction = async (inputs: I) => {
         return HL_CONTEXT.with(
             setDecoratorContext({
                 path: path,
@@ -139,7 +121,6 @@ export function flowUtilityFactory<I, O>(
         );
     };
 
-    // @ts-ignore
     return Object.assign(wrappedFunction, {
         file: {
             path: path,
diff --git a/src/decorators/tool.ts b/src/decorators/tool.ts
@@ -3,7 +3,6 @@ import { ReadableSpan } from "@opentelemetry/sdk-trace-node";
 
 import { ToolKernelRequest } from "../api/types/ToolKernelRequest";
 import { getEvaluationContext, getTraceId } from "../context";
-import { File as EvalRunFile } from "../evals/types";
 import { NestedDict, jsonifyIfNotString, writeToOpenTelemetrySpan } from "../otel";
 import {
     HUMANLOOP_FILE_KEY,
@@ -30,7 +29,6 @@ export function toolUtilityFactory<I, O>(
     path: string,
 ): (inputs: I) => O & {
     jsonSchema: Record<string, unknown>;
-    file: EvalRunFile<I, O>;
 } {
     const fileType = "tool";
 
@@ -96,11 +94,6 @@ export function toolUtilityFactory<I, O>(
     // @ts-ignore Adding jsonSchema property to utility-wrapped function
     return Object.assign(wrappedFunction, {
         jsonSchema: version.function || {},
-        decorator: {
-            type: fileType,
-            path: path,
-            version,
-        },
     });
 }
 
diff --git a/src/evals/run.ts b/src/evals/run.ts
@@ -117,11 +117,17 @@ async function pMap<T, O>(
     return result;
 }
 
-function callableIsHumanloopUtility<I, O>(file: File<I, O>): boolean {
+function callableIsHumanloopUtility<
+    I extends Record<string, unknown> & { messages?: any[] },
+    O,
+>(file: File<I, O>): boolean {
     return file.callable !== undefined && "decorator" in file.callable;
 }
 
-function fileOrFileInsideHLUtility<I, O>(file: File<I, O>): File<I, O> {
+function fileOrFileInsideHLUtility<
+    I extends Record<string, unknown> & { messages?: any[] },
+    O,
+>(file: File<I, O>): File<I, O> {
     if (callableIsHumanloopUtility(file)) {
         // @ts-ignore
         const innerFile: File<I, O> = file.callable!.file! as File<I, O>;
@@ -171,7 +177,9 @@ function fileOrFileInsideHLUtility<I, O>(file: File<I, O>): File<I, O> {
     }
 }
 
-function getFileType<I, O>(file: File<I, O>): FileType {
+function getFileType<I extends Record<string, unknown> & { messages?: any[] }, O>(
+    file: File<I, O>,
+): FileType {
     // Determine the `type` of the `file` to Evaluate - if not `type` provided, default to `flow`
     try {
         const type_ = file.type as FileType;
@@ -188,7 +196,7 @@ function getFileType<I, O>(file: File<I, O>): FileType {
     }
 }
 
-function getFileCallable<I, O>(
+function getFileCallable<I extends Record<string, unknown> & { messages?: any[] }, O>(
     file: File<I, O>,
     type_: FileType,
 ): File<I, O>["callable"] {
@@ -208,7 +216,10 @@ function getFileCallable<I, O>(
     return function_;
 }
 
-export async function runEval<I, O>(
+export async function runEval<
+    I extends Record<string, unknown> & { messages?: any[] },
+    O,
+>(
     client: HumanloopClient,
     file: File<I, O>,
     dataset: Dataset,
@@ -519,10 +530,10 @@ export async function runEval<I, O>(
     return checks;
 }
 
-async function callFunction<I, O>(
-    callable: File<I, O>["callable"],
-    datapoint: DatapointResponse,
-): Promise<string> {
+async function callFunction<
+    I extends Record<string, unknown> & { messages?: any[] },
+    O,
+>(callable: File<I, O>["callable"], datapoint: DatapointResponse): Promise<string> {
     const datapointDict = { ...datapoint };
     let output;
     if (callable === undefined) {
@@ -551,7 +562,7 @@ async function callFunction<I, O>(
     return output;
 }
 
-async function upsertFile<I, O>({
+async function upsertFile<I extends Record<string, unknown> & { messages?: any[] }, O>({
     file,
     type,
     client,
@@ -688,7 +699,10 @@ async function getNewRun({
     return { evaluation, run };
 }
 
-async function upsertLocalEvaluators<I, O>({
+async function upsertLocalEvaluators<
+    I extends Record<string, unknown> & { messages?: any[] },
+    O,
+>({
     evaluators,
     callable,
     type,
diff --git a/src/evals/types.ts b/src/evals/types.ts
@@ -47,7 +47,8 @@ interface Identifiers {
     path?: string;
 }
 
-export interface File<I, O> extends Identifiers {
+export interface File<I extends Record<string, unknown> & { messages?: any[] }, O>
+    extends Identifiers {
     /** The type of File this callable relates to on Humanloop. */
     type?: "flow" | "prompt";
     /** The contents uniquely define the version of the File on Humanloop. */
@@ -59,9 +60,7 @@ export interface File<I, O> extends Identifiers {
      * If messages are defined in your Dataset, then
      * `output = callable(datapoint.inputs, messages=datapoint.messages)`.
      */
-    callable?: I extends Record<string, unknown> & { messages?: ChatMessage[] }
-        ? (args: I) => O
-        : never;
+    callable?: (args: I) => O;
 }
 
 export interface Dataset extends Identifiers {
diff --git a/src/humanloop.client.ts b/src/humanloop.client.ts
@@ -1,8 +1,4 @@
 import { Tracer } from "@opentelemetry/api";
-import {
-    Instrumentation,
-    registerInstrumentations,
-} from "@opentelemetry/instrumentation";
 import { resourceFromAttributes } from "@opentelemetry/resources";
 import { NodeTracerProvider } from "@opentelemetry/sdk-trace-node";
 import { AnthropicInstrumentation } from "@traceloop/instrumentation-anthropic";
@@ -102,7 +98,7 @@ class ExtendedEvaluations extends BaseEvaluations {
      * @param evaluators - List of evaluators to be. Can be ran on Humanloop if specified only by path, or locally if a callable is provided.
      * @param concurrency - Number of datapoints to process in parallel.
      */
-    async run<I, O>({
+    async run<I extends Record<string, unknown> & { messages?: any[] }, O>({
         file,
         dataset,
         name,
@@ -122,14 +118,7 @@ class ExtendedEvaluations extends BaseEvaluations {
         )[];
         concurrency?: number;
     }): Promise<EvaluatorCheck[]> {
-        return runEval<I, O>(
-            this._client,
-            file,
-            dataset,
-            name,
-            evaluators,
-            concurrency,
-        );
+        return runEval(this._client, file, dataset, name, evaluators, concurrency);
     }
 }
 
@@ -293,7 +282,7 @@ export class HumanloopClient extends BaseHumanloopClient {
     }
 
     // Check if user has passed the LLM provider instrumentors
-    private assertProviders() {
+    private assertAtLeastOneProviderModuleSet() {
         const userDidNotPassProviders = Object.values(this.instrumentProviders).every(
             (provider) => !provider,
         );
@@ -406,20 +395,18 @@ ${RESET}`,
      * @param path - The path to the Prompt.
      */
     public prompt<I, O>(args: {
-        callable: I extends Record<string, unknown> & { messages?: ChatMessage[] }
-            ? (args: I) => O
-            : () => O;
+        callable: I extends never ? () => O : (args: I) => O;
         path: string;
-    }): I extends Record<string, unknown>
-        ? (
-              args: I,
-          ) => O extends Promise<infer R>
+    }): I extends never
+        ? () => O extends Promise<infer R>
               ? Promise<R | undefined>
               : Promise<O | undefined>
-        : () => O extends Promise<infer R>
+        : (
+              args: I,
+          ) => O extends Promise<infer R>
               ? Promise<R | undefined>
               : Promise<O | undefined> {
-        this.assertProviders();
+        this.assertAtLeastOneProviderModuleSet();
         // @ts-ignore
         return promptDecoratorFactory(args.path, args.callable);
     }
@@ -457,16 +444,20 @@ ${RESET}`,
      * @param version - The JSON Schema of the Tool's inputs and outputs, plus the optional Humanloop fields `attributes and `setupValues`. See API reference for details.
      */
     public tool<I, O>(args: {
-        callable: I extends Record<string, unknown> ? (args: I) => O : () => O;
+        callable: I extends never
+            ? () => O
+            : I extends Record<string, any>
+              ? (args: I) => O
+              : never;
         path: string;
         version: ToolKernelRequest;
-    }): I extends Record<string, unknown>
-        ? (
-              args: I,
-          ) => O extends Promise<infer R>
+    }): I extends never
+        ? () => O extends Promise<infer R>
               ? Promise<R | undefined>
               : Promise<O | undefined>
-        : () => O extends Promise<infer R>
+        : (
+              args: I,
+          ) => O extends Promise<infer R>
               ? Promise<R | undefined>
               : Promise<O | undefined> {
         // @ts-ignore
@@ -543,18 +534,20 @@ ${RESET}`,
         path,
         attributes,
     }: {
-        callable: I extends Record<string, unknown> & { messages?: ChatMessage[] }
-            ? ((args: I) => O) | (() => O)
-            : never;
+        callable: I extends never
+            ? () => O
+            : I extends Record<string, any> & { messages?: ChatMessage[] }
+              ? (args: I) => O
+              : never;
         path: string;
         attributes?: Record<string, unknown>;
-    }): I extends Record<string, unknown> & { messages?: ChatMessage[] }
-        ? (
-              args: I,
-          ) => O extends Promise<infer R>
+    }): I extends never
+        ? () => O extends Promise<infer R>
               ? Promise<R | undefined>
               : Promise<O | undefined>
-        : () => O extends Promise<infer R>
+        : (
+              args: I,
+          ) => O extends Promise<infer R>
               ? Promise<R | undefined>
               : Promise<O | undefined> {
         // @ts-ignore
