@prefactor/core 0.1.0

package/dist/index.js

@@ -0,0 +1,610 @@
+// packages/core/src/config.ts
+import { z } from "zod";
+var HttpTransportConfigSchema = z.object({
+  apiUrl: z.string().url(),
+  apiToken: z.string().min(1),
+  agentId: z.string().optional(),
+  agentVersion: z.string().optional(),
+  agentName: z.string().optional(),
+  agentDescription: z.string().optional(),
+  agentSchema: z.record(z.unknown()).optional(),
+  agentSchemaVersion: z.string().optional(),
+  skipSchema: z.boolean().default(false),
+  requestTimeout: z.number().positive().default(30000),
+  connectTimeout: z.number().positive().default(1e4),
+  maxRetries: z.number().int().nonnegative().default(3),
+  initialRetryDelay: z.number().positive().default(1000),
+  maxRetryDelay: z.number().positive().default(60000),
+  retryMultiplier: z.number().positive().default(2)
+});
+var PartialHttpConfigSchema = z.object({
+  apiUrl: z.string().url(),
+  apiToken: z.string().min(1),
+  agentId: z.string().optional(),
+  agentVersion: z.string().optional(),
+  agentName: z.string().optional(),
+  agentDescription: z.string().optional(),
+  agentSchema: z.record(z.unknown()).optional(),
+  agentSchemaVersion: z.string().optional(),
+  skipSchema: z.boolean().optional(),
+  requestTimeout: z.number().positive().optional(),
+  connectTimeout: z.number().positive().optional(),
+  maxRetries: z.number().int().nonnegative().optional(),
+  initialRetryDelay: z.number().positive().optional(),
+  maxRetryDelay: z.number().positive().optional(),
+  retryMultiplier: z.number().positive().optional()
+});
+var ConfigSchema = z.object({
+  transportType: z.enum(["stdio", "http"]).default("stdio"),
+  sampleRate: z.number().min(0).max(1).default(1),
+  captureInputs: z.boolean().default(true),
+  captureOutputs: z.boolean().default(true),
+  maxInputLength: z.number().int().positive().default(1e4),
+  maxOutputLength: z.number().int().positive().default(1e4),
+  httpConfig: PartialHttpConfigSchema.optional()
+});
+function createConfig(options) {
+  const config = {
+    transportType: options?.transportType ?? process.env.PREFACTOR_TRANSPORT ?? "stdio",
+    sampleRate: options?.sampleRate ?? parseFloat(process.env.PREFACTOR_SAMPLE_RATE ?? "1.0"),
+    captureInputs: options?.captureInputs ?? process.env.PREFACTOR_CAPTURE_INPUTS !== "false",
+    captureOutputs: options?.captureOutputs ?? process.env.PREFACTOR_CAPTURE_OUTPUTS !== "false",
+    maxInputLength: options?.maxInputLength ?? parseInt(process.env.PREFACTOR_MAX_INPUT_LENGTH ?? "10000", 10),
+    maxOutputLength: options?.maxOutputLength ?? parseInt(process.env.PREFACTOR_MAX_OUTPUT_LENGTH ?? "10000", 10),
+    httpConfig: options?.httpConfig
+  };
+  return ConfigSchema.parse(config);
+}
+// packages/core/src/tracing/context.ts
+import { AsyncLocalStorage } from "node:async_hooks";
+var spanStorage = new AsyncLocalStorage;
+
+class SpanContext {
+  static getCurrent() {
+    return spanStorage.getStore();
+  }
+  static run(span, fn) {
+    return spanStorage.run(span, fn);
+  }
+  static async runAsync(span, fn) {
+    return spanStorage.run(span, fn);
+  }
+  static clear() {
+    spanStorage.disable();
+  }
+}
+// packages/core/src/tracing/span.ts
+var SpanType;
+((SpanType2) => {
+  SpanType2["AGENT"] = "agent";
+  SpanType2["LLM"] = "llm";
+  SpanType2["TOOL"] = "tool";
+  SpanType2["CHAIN"] = "chain";
+  SpanType2["RETRIEVER"] = "retriever";
+})(SpanType ||= {});
+var SpanStatus;
+((SpanStatus2) => {
+  SpanStatus2["RUNNING"] = "running";
+  SpanStatus2["SUCCESS"] = "success";
+  SpanStatus2["ERROR"] = "error";
+})(SpanStatus ||= {});
+// packages/core/src/tracing/tracer.ts
+import { generate, generatePartition } from "@prefactor/pfid";
+class Tracer {
+  transport;
+  partition;
+  constructor(transport, partition) {
+    this.transport = transport;
+    this.partition = partition ?? generatePartition();
+  }
+  startSpan(options) {
+    const spanId = generate(this.partition);
+    const traceId = options.traceId ?? generate(this.partition);
+    const span = {
+      spanId,
+      parentSpanId: options.parentSpanId ?? null,
+      traceId,
+      name: options.name,
+      spanType: options.spanType,
+      startTime: Date.now(),
+      endTime: null,
+      status: "running" /* RUNNING */,
+      inputs: options.inputs,
+      outputs: null,
+      tokenUsage: null,
+      error: null,
+      metadata: options.metadata ?? {},
+      tags: options.tags ?? []
+    };
+    if (options.spanType === "agent") {
+      try {
+        this.transport.emit(span);
+      } catch (error) {
+        console.error("Failed to emit agent span:", error);
+      }
+    }
+    return span;
+  }
+  endSpan(span, options) {
+    span.endTime = Date.now();
+    span.outputs = options?.outputs ?? null;
+    span.tokenUsage = options?.tokenUsage ?? null;
+    if (options?.error) {
+      span.status = "error" /* ERROR */;
+      span.error = {
+        errorType: options.error.constructor.name,
+        message: options.error.message,
+        stacktrace: options.error.stack ?? ""
+      };
+    } else {
+      span.status = "success" /* SUCCESS */;
+    }
+    try {
+      if (span.spanType === "agent") {
+        this.transport.finishSpan(span.spanId, span.endTime);
+      } else {
+        this.transport.emit(span);
+      }
+    } catch (error) {
+      console.error("Failed to emit/finish span:", error);
+    }
+  }
+  startAgentInstance() {
+    try {
+      this.transport.startAgentInstance();
+    } catch (error) {
+      console.error("Failed to start agent instance:", error);
+    }
+  }
+  finishAgentInstance() {
+    try {
+      this.transport.finishAgentInstance();
+    } catch (error) {
+      console.error("Failed to finish agent instance:", error);
+    }
+  }
+  async close() {
+    try {
+      await this.transport.close();
+    } catch (error) {
+      console.error("Failed to close transport:", error);
+    }
+  }
+}
+// packages/core/src/utils/logging.ts
+class Logger {
+  namespace;
+  static level = 1 /* INFO */;
+  constructor(namespace) {
+    this.namespace = namespace;
+  }
+  debug(message, ...args) {
+    if (Logger.level <= 0 /* DEBUG */) {
+      console.debug(`[prefactor:${this.namespace}] ${message}`, ...args);
+    }
+  }
+  info(message, ...args) {
+    if (Logger.level <= 1 /* INFO */) {
+      console.info(`[prefactor:${this.namespace}] ${message}`, ...args);
+    }
+  }
+  warn(message, ...args) {
+    if (Logger.level <= 2 /* WARN */) {
+      console.warn(`[prefactor:${this.namespace}] ${message}`, ...args);
+    }
+  }
+  error(message, ...args) {
+    if (Logger.level <= 3 /* ERROR */) {
+      console.error(`[prefactor:${this.namespace}] ${message}`, ...args);
+    }
+  }
+  static setLevel(level) {
+    const levelMap = {
+      debug: 0 /* DEBUG */,
+      info: 1 /* INFO */,
+      warn: 2 /* WARN */,
+      error: 3 /* ERROR */
+    };
+    Logger.level = levelMap[level];
+  }
+}
+function getLogger(namespace) {
+  return new Logger(namespace);
+}
+function configureLogging() {
+  const level = process.env.PREFACTOR_LOG_LEVEL?.toLowerCase();
+  if (level) {
+    Logger.setLevel(level);
+  }
+}
+
+// packages/core/src/transport/http.ts
+var logger = getLogger("http-transport");
+
+class HttpTransport {
+  config;
+  queue = [];
+  processing = false;
+  closed = false;
+  agentInstanceId = null;
+  spanIdMap = new Map;
+  constructor(config) {
+    this.config = config;
+    this.startProcessing();
+  }
+  emit(span) {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({ type: "span", data: span });
+  }
+  finishSpan(spanId, endTime) {
+    if (this.closed) {
+      return;
+    }
+    const timestamp = new Date(endTime).toISOString();
+    this.queue.push({ type: "finish_span", data: { spanId, timestamp } });
+  }
+  startAgentInstance() {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({ type: "start_agent", data: null });
+  }
+  finishAgentInstance() {
+    if (this.closed) {
+      return;
+    }
+    this.queue.push({ type: "finish_agent", data: null });
+  }
+  async startProcessing() {
+    this.processing = true;
+    while (!this.closed || this.queue.length > 0) {
+      if (this.queue.length === 0) {
+        await new Promise((resolve) => setTimeout(resolve, 100));
+        continue;
+      }
+      const item = this.queue.shift();
+      if (!item)
+        continue;
+      try {
+        if (!this.agentInstanceId && item.type !== "start_agent") {
+          await this.ensureAgentRegistered();
+        }
+        switch (item.type) {
+          case "span":
+            await this.sendSpan(item.data);
+            break;
+          case "finish_span":
+            await this.finishSpanHttp(item.data);
+            break;
+          case "start_agent":
+            await this.startAgentInstanceHttp();
+            break;
+          case "finish_agent":
+            await this.finishAgentInstanceHttp();
+            break;
+        }
+      } catch (error) {
+        logger.error("Error processing queue item:", error);
+      }
+    }
+    this.processing = false;
+  }
+  async sendSpan(span, retry = 0) {
+    const url = `${this.config.apiUrl}/api/v1/agent_spans`;
+    const payload = this.transformSpanToApiFormat(span);
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiToken}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(this.config.requestTimeout)
+      });
+      if (response.ok) {
+        const data = await response.json();
+        const backendSpanId = data?.details?.id;
+        if (backendSpanId) {
+          this.spanIdMap.set(span.spanId, backendSpanId);
+        }
+        return;
+      }
+      if ((response.status >= 500 || response.status === 429) && retry < this.config.maxRetries) {
+        const delay = Math.min(this.config.initialRetryDelay * this.config.retryMultiplier ** retry, this.config.maxRetryDelay);
+        logger.debug(`Retrying span send after ${delay}ms (attempt ${retry + 1})`);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.sendSpan(span, retry + 1);
+      }
+      logger.error(`Failed to send span: ${response.status} ${response.statusText}`);
+    } catch (error) {
+      logger.error("Error sending span:", error);
+      if (retry < this.config.maxRetries) {
+        const delay = Math.min(this.config.initialRetryDelay * this.config.retryMultiplier ** retry, this.config.maxRetryDelay);
+        await new Promise((resolve) => setTimeout(resolve, delay));
+        return this.sendSpan(span, retry + 1);
+      }
+    }
+  }
+  transformSpanToApiFormat(span) {
+    const startedAt = new Date(span.startTime).toISOString();
+    const finishedAt = span.endTime ? new Date(span.endTime).toISOString() : null;
+    const payload = {
+      span_id: span.spanId,
+      trace_id: span.traceId,
+      name: span.name,
+      status: span.status,
+      inputs: span.inputs,
+      outputs: span.outputs,
+      metadata: span.metadata,
+      tags: span.tags,
+      token_usage: null,
+      error: null
+    };
+    if (span.tokenUsage) {
+      payload.token_usage = {
+        prompt_tokens: span.tokenUsage.promptTokens,
+        completion_tokens: span.tokenUsage.completionTokens,
+        total_tokens: span.tokenUsage.totalTokens
+      };
+    }
+    if (span.error) {
+      payload.error = {
+        error_type: span.error.errorType,
+        message: span.error.message,
+        stacktrace: span.error.stacktrace
+      };
+    }
+    const parentSpanId = span.parentSpanId ? this.spanIdMap.get(span.parentSpanId) ?? null : null;
+    return {
+      details: {
+        agent_instance_id: this.agentInstanceId,
+        schema_name: span.spanType,
+        payload,
+        parent_span_id: parentSpanId,
+        started_at: startedAt,
+        finished_at: finishedAt
+      }
+    };
+  }
+  getDefaultSchema() {
+    return {
+      external_identifier: "1.0.0",
+      span_schemas: {
+        agent: {
+          type: "object",
+          properties: { type: { type: "string", const: "agent" } }
+        },
+        llm: {
+          type: "object",
+          properties: { type: { type: "string", const: "llm" } }
+        },
+        tool: {
+          type: "object",
+          properties: { type: { type: "string", const: "tool" } }
+        },
+        chain: {
+          type: "object",
+          properties: { type: { type: "string", const: "chain" } }
+        },
+        retriever: {
+          type: "object",
+          properties: { type: { type: "string", const: "retriever" } }
+        }
+      }
+    };
+  }
+  async ensureAgentRegistered() {
+    if (this.agentInstanceId) {
+      return;
+    }
+    const url = `${this.config.apiUrl}/api/v1/agent_instance/register`;
+    const payload = {};
+    if (this.config.agentId)
+      payload.agent_id = this.config.agentId;
+    if (this.config.agentVersion) {
+      payload.agent_version = {
+        external_identifier: this.config.agentVersion,
+        name: this.config.agentName || "Agent",
+        description: this.config.agentDescription || ""
+      };
+    }
+    if (this.config.skipSchema) {
+      logger.debug("Skipping schema in registration (skipSchema=true)");
+    } else if (this.config.agentSchema) {
+      logger.debug("Using custom agent schema");
+      payload.agent_schema_version = this.config.agentSchema;
+    } else if (this.config.agentSchemaVersion) {
+      logger.debug(`Using schema version: ${this.config.agentSchemaVersion}`);
+      payload.agent_schema_version = {
+        external_identifier: this.config.agentSchemaVersion
+      };
+    } else {
+      logger.debug("Using default hardcoded schema (v1.0.0)");
+      payload.agent_schema_version = this.getDefaultSchema();
+    }
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiToken}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify(payload),
+        signal: AbortSignal.timeout(this.config.requestTimeout)
+      });
+      if (response.ok) {
+        const data = await response.json();
+        this.agentInstanceId = data?.details?.id ?? null;
+        logger.debug(`Registered agent instance: ${this.agentInstanceId}`);
+      } else {
+        logger.error(`Failed to register agent: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      logger.error("Error registering agent:", error);
+    }
+  }
+  async startAgentInstanceHttp() {
+    await this.ensureAgentRegistered();
+    if (!this.agentInstanceId) {
+      logger.error("Cannot start agent instance: not registered");
+      return;
+    }
+    const url = `${this.config.apiUrl}/api/v1/agent_instance/${this.agentInstanceId}/start`;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiToken}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(this.config.requestTimeout)
+      });
+      if (!response.ok) {
+        logger.error(`Failed to start agent instance: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      logger.error("Error starting agent instance:", error);
+    }
+  }
+  async finishAgentInstanceHttp() {
+    if (!this.agentInstanceId) {
+      logger.error("Cannot finish agent instance: not registered");
+      return;
+    }
+    const url = `${this.config.apiUrl}/api/v1/agent_instance/${this.agentInstanceId}/finish`;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiToken}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({}),
+        signal: AbortSignal.timeout(this.config.requestTimeout)
+      });
+      if (!response.ok) {
+        logger.error(`Failed to finish agent instance: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      logger.error("Error finishing agent instance:", error);
+    }
+  }
+  async finishSpanHttp(data) {
+    const backendSpanId = this.spanIdMap.get(data.spanId);
+    if (!backendSpanId) {
+      logger.warn(`Cannot finish span ${data.spanId}: backend ID not found`);
+      return;
+    }
+    const url = `${this.config.apiUrl}/api/v1/agent_spans/${backendSpanId}/finish`;
+    try {
+      const response = await fetch(url, {
+        method: "POST",
+        headers: {
+          Authorization: `Bearer ${this.config.apiToken}`,
+          "Content-Type": "application/json"
+        },
+        body: JSON.stringify({ timestamp: data.timestamp }),
+        signal: AbortSignal.timeout(this.config.requestTimeout)
+      });
+      if (!response.ok) {
+        logger.error(`Failed to finish span: ${response.status} ${response.statusText}`);
+      }
+    } catch (error) {
+      logger.error("Error finishing span:", error);
+    }
+  }
+  async close() {
+    this.closed = true;
+    const timeout = 1e4;
+    const start = Date.now();
+    while (this.processing && Date.now() - start < timeout) {
+      await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    if (this.processing) {
+      logger.warn("Transport closed with pending queue items");
+    }
+  }
+}
+// packages/core/src/utils/serialization.ts
+function truncateString(value, maxLength) {
+  if (value.length <= maxLength) {
+    return value;
+  }
+  return `${value.slice(0, maxLength)}... [truncated]`;
+}
+function serializeValue(value, maxLength = 1e4) {
+  if (value === null || value === undefined) {
+    return value;
+  }
+  if (typeof value === "boolean" || typeof value === "number") {
+    return value;
+  }
+  if (typeof value === "string") {
+    return maxLength !== null ? truncateString(value, maxLength) : value;
+  }
+  if (Array.isArray(value)) {
+    return value.map((item) => serializeValue(item, maxLength));
+  }
+  if (typeof value === "object") {
+    const result = {};
+    for (const [key, val] of Object.entries(value)) {
+      result[key] = serializeValue(val, maxLength);
+    }
+    return result;
+  }
+  try {
+    return String(value);
+  } catch {
+    return `<${typeof value} object>`;
+  }
+}
+
+// packages/core/src/transport/stdio.ts
+class StdioTransport {
+  closed = false;
+  writeLock = Promise.resolve();
+  emit(span) {
+    if (this.closed) {
+      return;
+    }
+    this.writeLock = this.writeLock.then(async () => {
+      try {
+        const serialized = serializeValue(span);
+        const json = JSON.stringify(serialized);
+        await Bun.write(Bun.stdout, `${json}
+`);
+      } catch (error) {
+        console.error("Failed to emit span to stdout:", error);
+      }
+    });
+  }
+  finishSpan() {}
+  startAgentInstance() {}
+  finishAgentInstance() {}
+  async close() {
+    this.closed = true;
+    await this.writeLock;
+  }
+}
+export {
+  truncateString,
+  serializeValue,
+  getLogger,
+  createConfig,
+  configureLogging,
+  Tracer,
+  StdioTransport,
+  SpanType,
+  SpanStatus,
+  SpanContext,
+  PartialHttpConfigSchema,
+  HttpTransportConfigSchema,
+  HttpTransport,
+  ConfigSchema
+};
+
+//# debugId=48E67D6DE4160D4864756E2164756E21