@gtcx/ai

Maturity: Scaffolding — API surface may change. Not recommended for production use without review. Coverage: ~50% (NAPI binding loader only; native .node artifacts not generated in CI)

Observability and tracing instrumentation for GTCX operations.

Provides traced() function wrappers that measure duration, log structured JSON to stderr, and capture errors — with zero external dependencies. Used by @gtcx/crypto and @gtcx/verification for operational telemetry and audit trails.

Installation

pnpm add @gtcx/ai

Quick Start

import { traced, createCategoryLogger } from '@gtcx/ai';

// Wrap a function with tracing
const classify = traced(
  async (data: unknown) => ({ category: 'gold', confidence: 0.97 }),
  'classify',
  { category: 'ai', logOutput: true }
);

// Scoped structured logger
const logger = createCategoryLogger('ai.classification');
logger.info('Done', { confidence: 0.97 });

API

| Export | Description | | -------------------------------- | ------------------------------------------------ | | traced(fn, name, opts?) | Wrap function with duration + structured logging | | withTrace(fn, name?, opts?) | Execute a no-arg function with tracing | | createCategoryLogger(category) | Scoped logger emitting JSON lines to stderr |

TracedOptions

| Option | Type | Description | | ---------------- | ------------------------------ | ------------------------------------ | | category | string | Logger category (default: default) | | logInput | boolean | Include sanitized input in logs | | logOutput | boolean | Include sanitized output in logs | | sanitizeInput | (input: unknown) => unknown | Redact sensitive inputs | | sanitizeOutput | (output: unknown) => unknown | Redact sensitive outputs | | metadata | Record<string, unknown> | Extra fields attached to every log |

No runtime dependencies. Safe to use in security-sensitive packages.

Related

• ADR-008: Optional Tracing via Peer Dependencies

License

MIT