ai-contract-observer 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Brandon Himpfen
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,253 @@
+# ai-contract-observer
+
+A lightweight observability layer for AI systems.
+
+This project solves a common problem in AI applications: even when requests and responses are structured, teams still struggle to understand what actually happened during a model interaction. Inputs are hard to trace, failures are difficult to diagnose, and system behavior becomes harder to improve over time.
+
+`ai-contract-observer` provides a small, practical logging and summary layer for AI interactions. It is designed to work especially well with `ai-contract-kit` but it can also be used with any structured request and response objects.
+
+It can be used as both a reference implementation and a lightweight standard for observing AI interactions.
+
+## Why this project exists
+
+Most AI systems are still hard to inspect.
+
+- One request succeeds but no one knows why.
+- Another fails and the error is only visible in application logs.
+- A third returns an uncertain output, but the system records it as a generic success.
+- A fourth performs poorly over time, but there is no consistent way to measure behavior across runs.
+
+The result is weak traceability, poor debugging, and limited operational visibility.
+
+This package defines a simple observation layer that sits around the model interaction boundary.
+
+## Mental model
+
+Think of the package as a small observability boundary:
+
+`App -> Request Contract -> Model -> Response Contract -> Observation Layer`
+
+The observer sits beside the application flow and records what happened in a consistent format.
+
+This does not replace model SDKs, tracing platforms, or application logging.
+
+It standardizes how AI interactions are logged, summarized, and inspected.
+
+## What is included
+
+- Observer instance for recording AI interactions.
+- Normalized event entries with IDs, timestamps, and durations.
+- Console logger for development visibility.
+- JSON logger for machine-readable output.
+- Summary helpers for status counts and success rates.
+- Example usage demonstrating real-world integration.
+- Test coverage for core observer behavior.
+
+## Install
+
+```bash
+npm install ai-contract-observer
+```
+
+## Example
+
+```js
+import { createObserver } from "ai-contract-observer";
+
+const observer = createObserver();
+
+const request = {
+  version: "1.0",
+  task: "summarization",
+  prompt: "Summarize this text in 3 sentences."
+};
+
+const response = {
+  version: "1.0",
+  status: "success",
+  output: {
+    text: "This is the summary."
+  },
+  meta: {
+    model: "example-model-v1"
+  }
+};
+
+observer.observe({
+  request,
+  response,
+  durationMs: 842
+});
+
+console.log(observer.getSummary());
+```
+
+## Event structure
+
+An observation entry looks like this:
+
+```json
+{
+  "id": "obs_000001",
+  "timestamp": "2026-03-22T00:00:00.000Z",
+  "durationMs": 842,
+  "request": {
+    "version": "1.0",
+    "task": "summarization",
+    "prompt": "Summarize this text in 3 sentences."
+  },
+  "response": {
+    "version": "1.0",
+    "status": "success",
+    "output": {
+      "text": "This is the summary."
+    },
+    "meta": {
+      "model": "example-model-v1"
+    }
+  }
+}
+```
+
+## Status summary
+
+The observer tracks the following response statuses:
+
+- `success`
+- `uncertain`
+- `refusal`
+- `error`
+- `unknown`
+
+This makes it easier to distinguish between valid results, low-confidence outputs, refusals, system errors, and malformed responses.
+
+## Quick wrapper example
+
+```js
+import { createObserver } from "ai-contract-observer";
+
+async function runModel(modelClient, request) {
+  const observer = createObserver();
+
+  const start = Date.now();
+
+  try {
+    const raw = await modelClient.generate(request);
+
+    const response = {
+      version: "1.0",
+      status: raw?.status ?? "unknown",
+      output: {
+        text: raw?.text ?? null,
+        structured: raw?.structured ?? null
+      },
+      meta: {
+        model: raw?.model ?? "unknown"
+      }
+    };
+
+    const entry = observer.observe({
+      request,
+      response,
+      durationMs: Date.now() - start
+    });
+
+    return { response, entry };
+  } catch (error) {
+    const response = {
+      version: "1.0",
+      status: "error",
+      output: {
+        text: null,
+        structured: null
+      },
+      issues: [
+        {
+          type: "exception",
+          message: error instanceof Error ? error.message : "Unknown error"
+        }
+      ],
+      meta: {
+        model: "unknown"
+      }
+    };
+
+    const entry = observer.observe({
+      request,
+      response,
+      durationMs: Date.now() - start
+    });
+
+    return { response, entry };
+  }
+}
+```
+
+## API
+
+### `createObserver(options?)`
+
+Creates a new observer instance.
+
+Supported options:
+
+- `logger`: an object with a `log(entry)` function.
+- `idPrefix`: string prefix for generated observation IDs.
+- `startSequence`: starting integer for generated IDs.
+
+### `observer.observe({ request, response, durationMs, timestamp? })`
+
+Records a single AI interaction and returns the normalized observation entry.
+
+### `observer.getEntries()`
+
+Returns a copy of all recorded entries.
+
+### `observer.getSummary()`
+
+Returns aggregate counts and derived metrics across recorded entries.
+
+### `observer.clear()`
+
+Removes all stored entries from the current observer instance.
+
+## Design Principles
+
+This project is intentionally minimal.
+
+It defines a small, explicit observability layer rather than a full telemetry platform. The goal is to provide a stable and understandable boundary for recording AI interactions without introducing unnecessary complexity.
+
+The design emphasizes:
+
+- Simplicity over abstraction
+- Explicit event structure over implicit logging
+- Reliability over feature sprawl
+- Composability over completeness
+
+This allows the observer to work across different models, tools, and systems while remaining easy to adopt.
+
+## Non-Goals
+
+This project does not attempt to:
+
+- Replace model SDKs or providers.
+- Replace full observability platforms.
+- Provide dashboards or hosted telemetry infrastructure.
+- Enforce a specific prompt strategy or orchestration framework.
+
+It focuses only on defining a consistent observation layer for AI interactions.
+
+## Roadmap
+
+This project is designed as a foundation for more observable AI systems. Future extensions may include:
+
+- File persistence adapters.
+- Streaming event hooks.
+- OpenTelemetry-compatible emitters.
+- Dashboard and reporting utilities.
+- Evaluation pipeline integration.
+- Trace correlation across multi-step AI workflows.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "ai-contract-observer",
+  "version": "0.1.0",
+  "description": "A lightweight observability layer for AI systems with structured request and response logging.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test",
+    "example": "node examples/basic-usage.js"
+  },
+  "keywords": [
+    "ai",
+    "llm",
+    "observability",
+    "logging",
+    "tracing",
+    "ai systems",
+    "ai infrastructure",
+    "structured outputs",
+    "inference"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/brandonhimpfen/ai-contract-observer.git"
+  },
+  "bugs": {
+    "url": "https://github.com/brandonhimpfen/ai-contract-observer/issues"
+  },
+  "homepage": "https://github.com/brandonhimpfen/ai-contract-observer#readme",
+  "author": "Brandon Himpfen",
+  "license": "MIT"
+}

package/src/index.js

@@ -0,0 +1,3 @@
+export { createObserver } from "./observer.js";
+export { createConsoleLogger, createJsonLogger } from "./logger.js";
+export { buildSummary, normalizeStatus } from "./summary.js";

package/src/logger.js

@@ -0,0 +1,46 @@
+function writeLine(writer, line) {
+  if (typeof writer === "function") {
+    writer(line);
+  }
+}
+
+export function createConsoleLogger(options = {}) {
+  const {
+    enabled = true,
+    writer = console.log
+  } = options;
+
+  return {
+    log(entry) {
+      if (!enabled) {
+        return;
+      }
+
+      const status = entry?.response?.status ?? "unknown";
+      const task = entry?.request?.task ?? "unknown";
+      const duration = entry?.durationMs ?? "n/a";
+
+      writeLine(
+        writer,
+        `[ai-contract-observer] ${entry.id} status=${status} task=${task} durationMs=${duration}`
+      );
+    }
+  };
+}
+
+export function createJsonLogger(options = {}) {
+  const {
+    writer = console.log,
+    pretty = false
+  } = options;
+
+  return {
+    log(entry) {
+      const json = pretty
+        ? JSON.stringify(entry, null, 2)
+        : JSON.stringify(entry);
+
+      writeLine(writer, json);
+    }
+  };
+}

package/src/observer.js

@@ -0,0 +1,100 @@
+import { createConsoleLogger } from "./logger.js";
+import { buildSummary, normalizeStatus } from "./summary.js";
+
+function formatSequence(sequence) {
+  return String(sequence).padStart(6, "0");
+}
+
+function clone(value) {
+  return value == null ? value : JSON.parse(JSON.stringify(value));
+}
+
+function normalizeTimestamp(timestamp) {
+  const date = timestamp ? new Date(timestamp) : new Date();
+
+  if (Number.isNaN(date.getTime())) {
+    throw new TypeError("timestamp must be a valid date or ISO string");
+  }
+
+  return date.toISOString();
+}
+
+function normalizeDuration(durationMs) {
+  if (durationMs == null) {
+    return null;
+  }
+
+  if (!Number.isFinite(durationMs) || durationMs < 0) {
+    throw new TypeError("durationMs must be a non-negative finite number");
+  }
+
+  return durationMs;
+}
+
+function createEntry({ id, timestamp, durationMs, request, response }) {
+  return {
+    id,
+    timestamp,
+    durationMs,
+    request: clone(request) ?? null,
+    response: clone(response) ?? null
+  };
+}
+
+export function createObserver(options = {}) {
+  const {
+    logger = createConsoleLogger({ enabled: false }),
+    idPrefix = "obs",
+    startSequence = 1
+  } = options;
+
+  if (!logger || typeof logger.log !== "function") {
+    throw new TypeError("logger must be an object with a log(entry) function");
+  }
+
+  if (!Number.isInteger(startSequence) || startSequence < 1) {
+    throw new TypeError("startSequence must be a positive integer");
+  }
+
+  let sequence = startSequence;
+  const entries = [];
+
+  function observe({ request = null, response = null, durationMs = null, timestamp } = {}) {
+    const id = `${idPrefix}_${formatSequence(sequence++)}`;
+    const normalizedTimestamp = normalizeTimestamp(timestamp);
+    const normalizedDuration = normalizeDuration(durationMs);
+
+    const entry = createEntry({
+      id,
+      timestamp: normalizedTimestamp,
+      durationMs: normalizedDuration,
+      request,
+      response
+    });
+
+    logger.log(entry);
+    entries.push(entry);
+
+    return clone(entry);
+  }
+
+  function getEntries() {
+    return clone(entries);
+  }
+
+  function getSummary() {
+    return buildSummary(entries);
+  }
+
+  function clear() {
+    entries.length = 0;
+  }
+
+  return {
+    observe,
+    getEntries,
+    getSummary,
+    clear,
+    normalizeStatus
+  };
+}

package/src/summary.js

@@ -0,0 +1,49 @@
+const KNOWN_STATUSES = new Set(["success", "uncertain", "refusal", "error"]);
+
+export function normalizeStatus(status) {
+  if (typeof status !== "string") {
+    return "unknown";
+  }
+
+  const value = status.trim().toLowerCase();
+  return KNOWN_STATUSES.has(value) ? value : "unknown";
+}
+
+export function buildSummary(entries = []) {
+  const summary = {
+    total: 0,
+    success: 0,
+    uncertain: 0,
+    refusal: 0,
+    error: 0,
+    unknown: 0,
+    successRate: 0,
+    averageDurationMs: null
+  };
+
+  let durationTotal = 0;
+  let durationCount = 0;
+
+  for (const entry of entries) {
+    summary.total += 1;
+
+    const status = normalizeStatus(entry?.response?.status);
+    summary[status] += 1;
+
+    const duration = entry?.durationMs;
+    if (Number.isFinite(duration)) {
+      durationTotal += duration;
+      durationCount += 1;
+    }
+  }
+
+  if (summary.total > 0) {
+    summary.successRate = Number((summary.success / summary.total).toFixed(4));
+  }
+
+  if (durationCount > 0) {
+    summary.averageDurationMs = Number((durationTotal / durationCount).toFixed(2));
+  }
+
+  return summary;
+}