@traccia2/sdk 0.0.1 → 0.0.3

package/src/integrations/auto-langchain.ts

@@ -0,0 +1,283 @@
+/**
+ * Automatic LangChain instrumentation - simple one-line setup.
+ * 
+ * Instead of manually passing callbacks to every component, use these
+ * convenience functions for automatic instrumentation with zero boilerplate.
+ */
+
+import { TraciaCallbackHandler } from './langchain-callback';
+
+/**
+ * Global handler instance to avoid creating multiple handlers
+ */
+let globalTraciaHandler: TraciaCallbackHandler | null = null;
+
+/**
+ * Get or create the global Traccia callback handler.
+ * 
+ * @example
+ * // Instead of:
+ * const handler = new TraciaCallbackHandler();
+ * const model = new ChatOpenAI({ callbacks: [handler] });
+ * 
+ * // Just do:
+ * const model = new ChatOpenAI({ callbacks: [getTraciaHandler()] });
+ */
+export function getTraciaHandler(): TraciaCallbackHandler {
+  if (!globalTraciaHandler) {
+    globalTraciaHandler = new TraciaCallbackHandler();
+  }
+  return globalTraciaHandler;
+}
+
+/**
+ * Wrap any LangChain model/chain/agent with automatic tracing.
+ * 
+ * @example
+ * const model = new ChatOpenAI({ modelName: 'gpt-4' });
+ * const tracedModel = withTracing(model);
+ * 
+ * const response = await tracedModel.invoke({ input: 'Hello' });
+ * // Automatically traced!
+ */
+export function withTracing<T extends any>(component: T): T {
+  const handler = getTraciaHandler();
+  
+  // For models and chains, add the handler to callbacks
+  if (component && typeof component === 'object') {
+    if ('callbacks' in component) {
+      // If callbacks exist, add our handler
+      const existing = (component as any).callbacks || [];
+      (component as any).callbacks = Array.isArray(existing) 
+        ? [...existing, handler] 
+        : [existing, handler];
+    } else {
+      // Otherwise create callbacks array
+      (component as any).callbacks = [handler];
+    }
+  }
+  
+  return component;
+}
+
+/**
+ * Create a traced ChatOpenAI model with one line.
+ * 
+ * @example
+ * const model = createTracedOpenAI({ modelName: 'gpt-4' });
+ * const response = await model.invoke({ input: 'Hello' });
+ */
+export async function createTracedOpenAI(config: any): Promise<any> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const langchainOpenai = require('@langchain/openai');
+    const model = new langchainOpenai.ChatOpenAI(config);
+    return withTracing(model);
+  } catch (error) {
+    throw new Error(
+      'Failed to create traced ChatOpenAI. Make sure @langchain/openai is installed.'
+    );
+  }
+}
+
+/**
+ * Create a traced agent executor with one line.
+ * 
+ * @example
+ * const executor = createTracedAgentExecutor({
+ *   agent,
+ *   tools,
+ *   agentExecutorOptions: { maxIterations: 10 }
+ * });
+ * 
+ * const result = await executor.invoke({ input: 'What time is it?' });
+ */
+export async function createTracedAgentExecutor(options: {
+  agent: any;
+  tools: any[];
+  agentExecutorOptions?: Record<string, any>;
+}): Promise<any> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const langchainAgents = require('langchain/agents');
+    const { agent, tools, agentExecutorOptions = {} } = options;
+    
+    const executor = langchainAgents.AgentExecutor.fromAgentAndTools({
+      agent,
+      tools,
+      ...agentExecutorOptions,
+      callbacks: [getTraciaHandler(), ...(agentExecutorOptions.callbacks || [])],
+    });
+    
+    return executor;
+  } catch (error) {
+    throw new Error(
+      'Failed to create traced AgentExecutor. Make sure langchain/agents is installed.'
+    );
+  }
+}
+
+/**
+ * Create a traced LLMChain with one line.
+ * 
+ * @example
+ * const chain = createTracedLLMChain({
+ *   llm: new ChatOpenAI(),
+ *   prompt: chatPrompt
+ * });
+ * 
+ * const result = await chain.invoke({ question: 'Hello?' });
+ */
+export async function createTracedLLMChain(options: {
+  llm: any;
+  prompt: any;
+}): Promise<any> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const langchainChains = require('langchain/chains');
+    const { llm, prompt } = options;
+    
+    const chain = new langchainChains.LLMChain({
+      llm: withTracing(llm),
+      prompt,
+      callbacks: [getTraciaHandler()],
+    });
+    
+    return chain;
+  } catch (error) {
+    throw new Error(
+      'Failed to create traced LLMChain. Make sure langchain/chains is installed.'
+    );
+  }
+}
+
+/**
+ * Decorator for methods that should be traced.
+ * 
+ * @example
+ * class MyAgent {
+ *   @traced('agent-process')
+ *   async process(input: string) {
+ *     return await this.llm.invoke({ input });
+ *   }
+ * }
+ * 
+ * const agent = new MyAgent();
+ * const result = await agent.process('Hello'); // Automatically traced!
+ */
+export function traced(spanName: string) {
+  return function (
+    _target: any,
+    propertyKey: string,
+    descriptor: PropertyDescriptor
+  ) {
+    const originalMethod = descriptor.value;
+
+    descriptor.value = async function (...args: any[]) {
+      const { getTracer } = await import('../auto');
+      const tracer = getTracer('decorated-method');
+      
+      return tracer.startActiveSpan(spanName, async (span) => {
+        try {
+          span.setAttribute('method', propertyKey);
+          span.setAttribute('args_count', args.length);
+          const result = await originalMethod.apply(this, args);
+          span.setAttribute('success', true);
+          return result;
+        } catch (error) {
+          if (error instanceof Error) {
+            span.recordException(error);
+          }
+          throw error;
+        }
+      });
+    };
+
+    return descriptor;
+  };
+}
+
+/**
+ * Simple configuration helper for common LangChain setup patterns.
+ * 
+ * @example
+ * const { model, executor } = await setupLangChainWithTracing({
+ *   modelName: 'gpt-4',
+ *   tools: [weatherTool, calculatorTool],
+ *   systemPrompt: 'You are a helpful assistant.'
+ * });
+ * 
+ * const result = await executor.invoke({ input: 'What is the weather?' });
+ */
+export async function setupLangChainWithTracing(options: {
+  modelName?: string;
+  modelConfig?: Record<string, any>;
+  tools?: any[];
+  systemPrompt?: string;
+}): Promise<{
+  model: any;
+  executor: any;
+  handler: TraciaCallbackHandler;
+}> {
+  try {
+    const {
+      modelName = 'gpt-4',
+      modelConfig = {},
+      tools = [],
+      systemPrompt,
+    } = options;
+
+    // Create traced model
+    const model = await createTracedOpenAI({
+      modelName,
+      ...modelConfig,
+    });
+
+    // Create agent if tools provided
+    let executor = null;
+    if (tools.length > 0) {
+      try {
+        // Try to create agent with tools
+        const langchainAgents = require('langchain/agents');
+        const langchainCore = require('@langchain/core/prompts');
+
+        // Create prompt
+        const prompt = langchainCore.ChatPromptTemplate.fromMessages([
+          ...(systemPrompt
+            ? [['system', systemPrompt]]
+            : [['system', 'You are a helpful assistant.']]),
+          ['human', '{input}'],
+          new langchainCore.MessagesPlaceholder('agent_scratchpad'),
+        ]);
+
+        // Create agent
+        const agent = await langchainAgents.createOpenAIToolsAgent({
+          llmWithTools: model,
+          tools,
+          prompt,
+          callbacks: [getTraciaHandler()],
+        });
+
+        // Create executor
+        executor = await createTracedAgentExecutor({
+          agent,
+          tools,
+        });
+      } catch (error) {
+        // If agent creation fails, just return model without executor
+        console.warn('Could not create agent executor:', (error as Error).message);
+      }
+    }
+
+    return {
+      model,
+      executor,
+      handler: getTraciaHandler(),
+    };
+  } catch (error) {
+    const err = error as Error;
+    throw new Error(
+      `Failed to setup LangChain with tracing: ${err.message}`
+    );
+  }
+}

package/src/integrations/auto-langgraph.ts

@@ -0,0 +1,248 @@
+/**
+ * Automatic LangGraph instrumentation - simple one-line setup.
+ * 
+ * Wrap your LangGraph nodes and conditionals to get tracing without
+ * any boilerplate code.
+ */
+
+import {
+  instrumentLangGraph,
+  createTracedNode,
+  createTracedConditional,
+} from './langgraph-instrumentation';
+
+/**
+ * Wrap a StateGraph with automatic tracing.
+ * 
+ * @example
+ * const graph = new StateGraph(GraphState);
+ * graph.addNode('step1', processStep1);
+ * graph.addNode('step2', processStep2);
+ * graph.addEdge('step1', 'step2');
+ * 
+ * // Just wrap your graph!
+ * const traced = wrapGraphWithTracing(graph);
+ * const compiled = traced.compile();
+ * 
+ * const result = await compiled.invoke({ input: 'data' });
+ * // Fully traced with no other changes!
+ */
+export function wrapGraphWithTracing(graph: any, options: any = {}): any {
+  return instrumentLangGraph(graph, {
+    traceGraphExecution: true,
+    traceNodeExecution: true,
+    captureGraphState: options.captureState ?? false,
+    ...options,
+  });
+}
+
+/**
+ * Create a traced node function with one line.
+ * 
+ * @example
+ * // Wrap your existing node:
+ * const existingNode = (state) => ({ result: 'done' });
+ * const traced = tracedNode('process-step', existingNode);
+ * graph.addNode('process', traced);
+ */
+export function tracedNode(
+  nodeName: string,
+  nodeFunction: (state: any) => Promise<any> | any
+): (state: any) => Promise<any> {
+  return createTracedNode(nodeName, nodeFunction);
+}
+
+/**
+ * Create a traced conditional edge router with one line.
+ * 
+ * @example
+ * // Wrap your existing router:
+ * const decideRoute = (state) => state.approved ? 'done' : 'review';
+ * const traced = tracedConditional('route-check', decideRoute);
+ * graph.addConditionalEdges('check', traced);
+ */
+export function tracedConditional(
+  conditionalName: string,
+  routeFunction: (state: Record<string, any>) => string
+): (state: Record<string, any>) => string {
+  return createTracedConditional(conditionalName, routeFunction);
+}
+
+/**
+ * Factory function to create a traced agent graph from simple config.
+ * 
+ * @example
+ * const graph = createSimpleTracedGraph({
+ *   nodes: {
+ *     'process': async (state) => ({ result: await process(state.input) }),
+ *     'review': async (state) => ({ reviewed: true }),
+ *   },
+ *   edges: [
+ *     { from: '__start__', to: 'process' },
+ *     { from: 'process', to: 'review' },
+ *     { from: 'review', to: '__end__' },
+ *   ],
+ * });
+ * 
+ * const result = await graph.compile().invoke({ input: 'data' });
+ */
+export async function createSimpleTracedGraph(options: {
+  nodes: Record<string, (state: any) => Promise<any>>;
+  edges: Array<{ from: string; to: string }>;
+  conditionals?: Record<
+    string,
+    { router: (state: any) => string; routes: string[] }
+  >;
+  startState?: Record<string, any>;
+}): Promise<any> {
+  try {
+    // eslint-disable-next-line @typescript-eslint/no-var-requires
+    const langgraphModule = require('@langchain/langgraph');
+    const { nodes, edges, conditionals = {}, startState = {} } = options;
+
+    // Create state graph
+    const graph = new langgraphModule.StateGraph({
+      channels: startState,
+    });
+
+    // Add traced nodes
+    for (const [nodeName, nodeFunc] of Object.entries(nodes)) {
+      const tracedNodeFunc = tracedNode(nodeName, nodeFunc);
+      graph.addNode(nodeName, tracedNodeFunc);
+    }
+
+    // Add edges
+    for (const edge of edges) {
+      if (edge.from === '__start__') {
+        graph.setEntryPoint(edge.to);
+      } else if (edge.to === '__end__') {
+        graph.setFinishPoint(edge.from);
+      } else {
+        graph.addEdge(edge.from, edge.to);
+      }
+    }
+
+    // Add conditional edges
+    for (const [condName, condConfig] of Object.entries(conditionals)) {
+      const tracedRouter = tracedConditional(condName, condConfig.router);
+      graph.addConditionalEdges(condName, tracedRouter, condConfig.routes);
+    }
+
+    // Wrap entire graph with tracing
+    return wrapGraphWithTracing(graph);
+  } catch (error) {
+    const err = error as Error;
+    throw new Error(
+      `Failed to create simple traced graph: ${err.message}. Make sure @langchain/langgraph is installed.`
+    );
+  }
+}
+
+/**
+ * Trace a single agent function or tool with minimal setup.
+ * 
+ * @example
+ * const tool = traceableFunction('my-tool', async (input) => {
+ *   return processInput(input);
+ * });
+ * 
+ * const result = await tool('data');
+ * // Automatically traced!
+ */
+export function traceableFunction<T extends (...args: any[]) => any>(
+  spanName: string,
+  fn: T
+): T {
+  return (async (...args: any[]) => {
+    const { getTracer } = await import('../auto');
+    const tracer = getTracer('traceable-function');
+
+    return tracer.startActiveSpan(spanName, async (span) => {
+      try {
+        span.setAttribute('args_count', args.length);
+        if (args[0] && typeof args[0] === 'object') {
+          span.setAttribute('input_keys', Object.keys(args[0]).join(','));
+        }
+
+        const result = await fn(...args);
+
+        if (result && typeof result === 'object') {
+          span.setAttribute('output_keys', Object.keys(result).join(','));
+        }
+        span.setAttribute('success', true);
+
+        return result;
+      } catch (error) {
+        if (error instanceof Error) {
+          span.recordException(error);
+        }
+        throw error;
+      }
+    });
+  }) as T;
+}
+
+/**
+ * Quick setup for a common agent pattern: input → process → route → output.
+ * 
+ * @example
+ * const graph = await createAgentWorkflow({
+ *   processInput: async (state) => ({ processed: await analyze(state.input) }),
+ *   routeDecision: (state) => state.processed.needsReview ? 'review' : 'done',
+ *   reviewStep: async (state) => ({ reviewed: true }),
+ * });
+ * 
+ * const result = await graph.compile().invoke({ input: 'user input' });
+ */
+export async function createAgentWorkflow(options: {
+  processInput: (state: Record<string, any>) => Promise<Record<string, any>>;
+  routeDecision: (state: Record<string, any>) => string;
+  reviewStep?: (state: Record<string, any>) => Promise<Record<string, any>>;
+  finalStep?: (state: Record<string, any>) => Promise<Record<string, any>>;
+}): Promise<any> {
+  try {
+    const {
+      processInput,
+      routeDecision,
+      reviewStep,
+      finalStep,
+    } = options;
+
+    const nodes: Record<string, (state: any) => Promise<any>> = {
+      process: processInput,
+    };
+
+    if (reviewStep) nodes.review = reviewStep;
+    if (finalStep) nodes.final = finalStep;
+
+    const edges: Array<{ from: string; to: string }> = [
+      { from: '__start__', to: 'process' },
+    ];
+
+    const conditionals: Record<string, any> = {
+      route: {
+        router: routeDecision,
+        routes: ['done', ...(reviewStep ? ['review'] : [])],
+      },
+    };
+
+    edges.push({ from: 'process', to: 'route' });
+
+    if (reviewStep) {
+      edges.push({ from: 'review', to: finalStep ? 'final' : '__end__' });
+    }
+
+    if (finalStep) {
+      edges.push({ from: 'final', to: '__end__' });
+    }
+
+    return createSimpleTracedGraph({
+      nodes,
+      edges,
+      conditionals,
+    });
+  } catch (error) {
+    const err = error as Error;
+    throw new Error(`Failed to create agent workflow: ${err.message}`);
+  }
+}

package/src/integrations/index.ts

@@ -5,9 +5,39 @@
  * @module integrations
  */
 
+// LangChain integrations
 export { TraciaCallbackHandler } from './langchain-callback';
+export {
+  getTraciaHandler,
+  withTracing,
+  createTracedOpenAI,
+  createTracedAgentExecutor,
+  createTracedLLMChain,
+  traced,
+  setupLangChainWithTracing,
+} from './auto-langchain';
+
+// LangGraph integrations
 export {
   instrumentLangGraph,
   createTracedNode,
   createTracedConditional,
 } from './langgraph-instrumentation';
+export {
+  wrapGraphWithTracing,
+  tracedNode,
+  tracedConditional,
+  createSimpleTracedGraph,
+  traceableFunction,
+  createAgentWorkflow,
+} from './auto-langgraph';
+
+// Ollama integrations
+export {
+  createOllamaWithTracing,
+  setupOllamaWithTracing,
+  createOllamaChatbot,
+  createOllamaStreamingChatbot,
+  getOllamaSetupInstructions,
+  POPULAR_OLLAMA_MODELS,
+} from './ollama-integration';