zayra-provider 0.0.1

package/README.md

@@ -0,0 +1,251 @@
+# zayra-provider
+
+The universal AI provider integration layer of **ZAYRA AI**. It defines one standard interface every AI platform connects through — Groq, Gemini, OpenAI, OpenRouter, local models, and custom providers — so ZAYRA can connect, manage, and use any of them the same way.
+
+## Installation
+
+```bash
+npm install zayra-provider
+```
+
+## Usage
+
+```js
+import { createProvider, ProviderRegistry } from "zayra-provider";
+
+const geminiProvider = createProvider({
+  name: "gemini",
+  async models() {
+    return [{ name: "gemini-2.0-flash", capabilities: ["chat"], contextLength: 32000, speed: "fast" }];
+  },
+  async chat(request) { /* call Gemini's chat API */ },
+  async generate(request) { /* call Gemini's generate API */ },
+  async status() { return { status: "online" }; },
+});
+
+const registry = new ProviderRegistry();
+registry.register(geminiProvider);
+
+const response = await registry.chat("gemini", { messages: [{ role: "user", content: "hi" }] });
+```
+
+## The provider interface
+
+Every provider supports exactly five members:
+
+```
+name        -> string
+models()    -> Promise<ModelInfo[]>
+chat()      -> Promise<any>
+generate()  -> Promise<any>
+status()    -> Promise<{ status, details? }>
+```
+
+```
+Provider -> Model list -> AI request
+```
+
+Two ways to build one:
+
+**Extend `BaseProvider`** (batteries included — a credential helper, and unoverridden methods throw a clear error instead of doing nothing):
+
+```js
+import { BaseProvider } from "zayra-provider";
+
+class GroqProvider extends BaseProvider {
+  constructor() { super({ name: "groq" }); }
+  async models() { /* ... */ }
+  async chat(request) {
+    const apiKey = this.resolveApiKey(); // never stored on `this`
+    /* ... */
+  }
+  async generate(request) { /* ... */ }
+  async status() { /* ... */ }
+}
+```
+
+**Or use `createProvider()`** for a quick functional provider from plain functions (shown in Usage above). Both approaches produce the same validated shape — `isValidProvider(x)` checks structurally, not via `instanceof`.
+
+## Supported provider types
+
+Groq, Gemini, OpenAI, OpenRouter, Local Models, and Custom Providers are all just implementations of the same interface — nothing about the architecture favors one platform, and adding a new one means writing one more conforming object. zayra-provider itself doesn't ship concrete Groq/Gemini/OpenAI/OpenRouter clients (those are separate plugin packages, e.g. `groq-provider`, `gemini-provider` — see Plugin Compatibility below); it defines and manages the interface they all implement.
+
+## Dynamic provider registration
+
+```js
+registry.register(GeminiProvider);
+registry.unregister("gemini");
+registry.list();     // ["gemini", ...]
+registry.has("gemini");
+```
+
+## Model Information System
+
+```js
+await registry.listModels("gemini");
+// [{ name, capabilities, contextLength, speed, available }, ...]
+```
+
+Every provider reports this consistently — `normalizeModelInfo()` fills in defaults (`speed: "balanced"`, `available: true`, `capabilities: []`) for whatever a provider omits.
+
+## Provider health check
+
+Every call made *through the registry* (`chat`, `generate`, `checkStatus`) is automatically timed and recorded:
+
+```js
+await registry.chat("gemini", { messages: [...] });
+
+registry.getHealth("gemini");
+// { status: "online", lastCheckedAt, lastError, callCount, errorCount, averageResponseTimeMs }
+
+await registry.checkAllStatus(); // pings every registered provider, tolerant of individual failures
+```
+
+Status is `"online"` after a recent success, `"offline"` immediately after a failure, and `"degraded"` if the overall failure rate crosses 50% even though the most recent call succeeded.
+
+## API key management
+
+zayra-provider never stores an API key. `resolveApiKey()` reads one on demand, checking a `zayra-config`-shaped object first (if given), then environment variables using the same `<PROVIDER_NAME>_API_KEY` convention `zayra-config` uses:
+
+```js
+import { resolveApiKey } from "zayra-provider";
+
+const key = resolveApiKey("groq", { config: myZayraConfigManager }); // or just { env: process.env }
+```
+
+```bash
+# .env
+GROQ_API_KEY=...
+GEMINI_API_KEY=...
+```
+
+## Automatic provider switching (fallback communication)
+
+zayra-provider makes failures typed and observable (`AuthenticationError` / `ConnectionError` / `ModelError`) and tracks health — that's what lets an orchestrator decide to switch. **Choosing which provider to try next is zayra-ai-router's job** (its `FallbackManager`), not this package's — per the "no model selection decisions" rule below. To connect the two:
+
+```js
+import { toRouterProviderPlugin } from "zayra-provider";
+import { AIRouter } from "zayra-ai-router";
+
+const router = new AIRouter();
+router.registerProvider(toRouterProviderPlugin(geminiProvider));
+router.registerProvider(toRouterProviderPlugin(groqProvider));
+
+await router.discoverModels();
+await router.route({ task: "chat" }); // groq fails -> automatically tries gemini
+```
+
+`toRouterProviderPlugin()` is a pure shape translation (`chat`/`generate` -> `invoke`, `status` -> `isAvailable`, `contextLength` -> `contextSize`) — it doesn't decide anything itself.
+
+## Plugin compatibility
+
+Providers are plugins. Real integrations live in their own packages and register into a `ProviderRegistry`:
+
+```
+plugins/
+  groq-provider
+  gemini-provider
+  custom-provider
+```
+
+## Local provider support
+
+Local runners (Ollama, self-hosted models) are wired up via an injectable **transport** — the part that actually talks to your local runner — rather than a hardcoded, unverified HTTP client:
+
+```js
+import { createLocalProvider } from "zayra-provider";
+
+const local = createLocalProvider({
+  name: "local",
+  transport: {
+    async chat(request) {
+      const res = await fetch("http://localhost:11434/api/chat", {
+        method: "POST",
+        body: JSON.stringify({ model: request.model, messages: request.messages }),
+      });
+      if (!res.ok) throw new Error(`Ollama returned ${res.status}`);
+      return res.json();
+    },
+    async ping() {
+      const res = await fetch("http://localhost:11434/api/tags");
+      return res.ok;
+    },
+  },
+  models: [{ name: "llama3", speed: "balanced" }],
+});
+```
+
+The Ollama wiring above is illustrative — zayra-provider doesn't ship or test a live Ollama integration itself; you supply the transport for whatever you're actually running.
+
+## Errors
+
+- `ProviderError` — base error class; carries `err.providerName`
+- `AuthenticationError` — invalid/missing/expired API key
+- `ConnectionError` — network failure (including a local runner being unreachable)
+- `ModelError` — requested model unavailable/unknown
+
+```js
+import { AuthenticationError, ConnectionError } from "zayra-provider";
+
+try {
+  await registry.chat("groq", { messages: [...] });
+} catch (err) {
+  if (err instanceof AuthenticationError) {
+    console.error("Bad API key for", err.providerName);
+  }
+}
+```
+
+## What this package deliberately does NOT do
+
+Per its design rules:
+
+- No frontend UI
+- No user accounts
+- No hardcoded API keys
+- No model selection decisions — every registry method takes an explicit provider `name`; choosing *which* one is zayra-ai-router's job
+
+It only manages the connection between ZAYRA and AI platforms.
+
+## Project structure
+
+```
+zayra-provider/
+  src/
+    index.js        # public entry point
+    provider.js       # standard interface, BaseProvider, createProvider(), router adapter
+    registry.js         # ProviderRegistry (dynamic registration + health wiring)
+    models.js             # Model Information System
+    health.js               # ProviderHealthMonitor
+    credentials.js            # API key resolution (never stored)
+    local.js                    # local/self-hosted provider support
+    errors.js                     # ProviderError, AuthenticationError, ConnectionError, ModelError
+  package.json
+  README.md
+```
+
+## API reference
+
+### `class ProviderRegistry`
+
+| Method | Description |
+| --- | --- |
+| `register(provider)` | Registers a provider. |
+| `unregister(name)` | Removes a provider and its health history. |
+| `get(name)` / `has(name)` / `list()` | Lookup. |
+| `listModels(name)` | Delegates to the provider's `models()`. |
+| `chat(name, request)` / `generate(name, request)` | Health-tracked calls. |
+| `checkStatus(name)` / `checkAllStatus()` | Health-tracked `status()` calls. |
+| `getHealth(name)` / `getAllHealth()` | Reads recorded health. |
+
+### Other exports
+
+`BaseProvider`, `createProvider()`, `isValidProvider()`, `toRouterProviderPlugin()`, `createLocalProvider()`, `normalizeModelInfo()`, `isValidModelInfo()`, `ProviderHealthMonitor`, `HealthStatus`, `getApiKeyFromEnv()`, `resolveApiKey()`, `ProviderError`, `AuthenticationError`, `ConnectionError`, `ModelError`
+
+## Compatibility
+
+Designed to work with `zayra-core`, `zayra-config`, `zayra-ai-router`, and `zayra-plugins`.
+
+## License
+
+MIT

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "zayra-provider",
+  "version": "0.0.1",
+  "description": "Universal AI provider integration layer for ZAYRA AI — a standard connection interface for Groq, Gemini, OpenAI, OpenRouter, local models, and custom providers.",
+  "type": "module",
+  "main": "src/index.js",
+  "exports": {
+    ".": "./src/index.js"
+  },
+  "files": [
+    "src",
+    "README.md"
+  ],
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "scripts": {
+    "test": "node --test \"test/**/*.test.js\""
+  },
+  "keywords": [
+    "zayra",
+    "ai",
+    "provider",
+    "groq",
+    "gemini",
+    "openai",
+    "openrouter",
+    "ollama"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {}
+}

package/src/credentials.js

@@ -0,0 +1,60 @@
+/**
+ * credentials.js
+ *
+ * API Key Management (spec section: "API Key Management"). Resolves
+ * a provider's credential on demand — it is never stored, cached, or
+ * persisted anywhere in this package.
+ *
+ * Two sources, in priority order:
+ *   1. A zayra-config-shaped object, if given (duck-typed — anything
+ *      with a getProviderApiKey(name) method works, so this package
+ *      never takes a hard dependency on zayra-config itself).
+ *   2. Environment variables, using the same <NAME>_API_KEY
+ *      convention zayra-config uses, so a key set either place is
+ *      picked up consistently across the ecosystem.
+ */
+
+const API_KEY_SUFFIX = "_API_KEY";
+
+/**
+ * Reads a provider's API key directly from an env-like map, using
+ * the `<PROVIDER_NAME>_API_KEY` convention (e.g. "groq" -> GROQ_API_KEY).
+ *
+ * @param {string} providerName
+ * @param {Record<string, string>} [env] - Defaults to process.env.
+ * @returns {string|undefined}
+ */
+export function getApiKeyFromEnv(providerName, env = process.env) {
+  return env[`${providerName.toUpperCase()}${API_KEY_SUFFIX}`];
+}
+
+/**
+ * Resolves a provider's API key: tries a zayra-config-shaped object
+ * first (if given), then falls back to environment variables.
+ * Returns undefined (not an error) if no key is configured anywhere
+ * — callers decide whether that's fatal for them (e.g. by throwing
+ * AuthenticationError themselves).
+ *
+ * @param {string} providerName
+ * @param {object} [options]
+ * @param {{ getProviderApiKey?: (name: string) => string|undefined }} [options.config] - A zayra-config ConfigManager instance, or anything shaped like one.
+ * @param {Record<string, string>} [options.env] - Defaults to process.env.
+ * @returns {string|undefined}
+ */
+export function resolveApiKey(providerName, options = {}) {
+  const { config, env = process.env } = options;
+
+  if (config && typeof config.getProviderApiKey === "function") {
+    const fromConfig = config.getProviderApiKey(providerName);
+    if (fromConfig) {
+      return fromConfig;
+    }
+  }
+
+  return getApiKeyFromEnv(providerName, env);
+}
+
+export default {
+  getApiKeyFromEnv,
+  resolveApiKey,
+};

package/src/errors.js

@@ -0,0 +1,74 @@
+/**
+ * errors.js
+ *
+ * Custom error hierarchy for zayra-provider. Never fails silently —
+ * every error thrown inside this package is one of these classes, so
+ * callers (including zayra-ai-router, deciding whether to fall back)
+ * can branch on error type rather than parsing messages.
+ */
+
+/**
+ * Base error class for all zayra-provider errors.
+ */
+export class ProviderError extends Error {
+  /**
+   * @param {string} message
+   * @param {object} [options]
+   * @param {string} [options.code]
+   * @param {string} [options.providerName]
+   * @param {unknown} [options.cause]
+   */
+  constructor(message, options = {}) {
+    super(message);
+
+    this.name = this.constructor.name;
+    this.code = options.code ?? "PROVIDER_ERROR";
+    this.providerName = options.providerName ?? null;
+
+    if (options.cause !== undefined) {
+      this.cause = options.cause;
+    }
+
+    if (typeof Error.captureStackTrace === "function") {
+      Error.captureStackTrace(this, this.constructor);
+    }
+  }
+}
+
+/**
+ * Thrown when a provider rejects a request due to a missing, invalid,
+ * or expired API key/credential.
+ */
+export class AuthenticationError extends ProviderError {
+  constructor(message, options = {}) {
+    super(message, { code: "AUTHENTICATION_ERROR", ...options });
+  }
+}
+
+/**
+ * Thrown for network-level failures: timeouts, DNS/connection
+ * failures, unreachable hosts (including a local runner like Ollama
+ * not running).
+ */
+export class ConnectionError extends ProviderError {
+  constructor(message, options = {}) {
+    super(message, { code: "CONNECTION_ERROR", ...options });
+  }
+}
+
+/**
+ * Thrown when a requested model is unavailable, unknown to the
+ * provider, or otherwise can't serve the request.
+ */
+export class ModelError extends ProviderError {
+  constructor(message, options = {}) {
+    super(message, { code: "MODEL_ERROR", ...options });
+  }
+}
+
+export default {
+  ProviderError,
+  AuthenticationError,
+  ConnectionError,
+  ModelError,
+};

package/src/health.js

@@ -0,0 +1,125 @@
+/**
+ * health.js
+ *
+ * Provider Health Check (spec section: "Provider Health Check").
+ * Tracks online/offline status, errors, and response time per
+ * provider, purely as in-memory bookkeeping. ProviderRegistry
+ * updates this automatically whenever it calls through to a
+ * provider — see registry.js.
+ */
+
+/**
+ * @readonly
+ * @enum {string}
+ */
+export const HealthStatus = Object.freeze({
+  ONLINE: "online",
+  OFFLINE: "offline",
+  DEGRADED: "degraded",
+  UNKNOWN: "unknown",
+});
+
+const DEGRADED_FAILURE_RATE_THRESHOLD = 0.5;
+
+/**
+ * Tracks a single provider's health over time.
+ *
+ * @example
+ * const health = new ProviderHealthMonitor();
+ * health.recordSuccess(120);
+ * health.getStatus(); // { status: "online", ... }
+ */
+export class ProviderHealthMonitor {
+  constructor() {
+    this._status = HealthStatus.UNKNOWN;
+    this._lastCheckedAt = null;
+    this._lastError = null;
+    this._callCount = 0;
+    this._errorCount = 0;
+    this._totalResponseTimeMs = 0;
+    this._successResponseCount = 0;
+  }
+
+  /**
+   * Records a successful call.
+   * @param {number} responseTimeMs
+   */
+  recordSuccess(responseTimeMs) {
+    this._callCount += 1;
+    this._successResponseCount += 1;
+    this._totalResponseTimeMs += responseTimeMs;
+    this._lastCheckedAt = new Date().toISOString();
+    this._lastError = null;
+    this._status = this._computeStatus();
+  }
+
+  /**
+   * Records a failed call.
+   * @param {Error|unknown} [error]
+   */
+  recordFailure(error) {
+    this._callCount += 1;
+    this._errorCount += 1;
+    this._lastCheckedAt = new Date().toISOString();
+    this._lastError = error?.message ?? (error !== undefined ? String(error) : "Unknown error");
+    this._status = this._computeStatus();
+  }
+
+  /**
+   * Derives online/offline/degraded from recent call history. The
+   * most recent call matters most (a single failure right now means
+   * "offline", not "degraded"), while the overall failure rate
+   * nudges an otherwise-successful provider to "degraded".
+   * @returns {string}
+   * @private
+   */
+  _computeStatus() {
+    if (this._callCount === 0) {
+      return HealthStatus.UNKNOWN;
+    }
+
+    if (this._lastError !== null) {
+      return HealthStatus.OFFLINE;
+    }
+
+    const failureRate = this._errorCount / this._callCount;
+    return failureRate >= DEGRADED_FAILURE_RATE_THRESHOLD ? HealthStatus.DEGRADED : HealthStatus.ONLINE;
+  }
+
+  /**
+   * @returns {{
+   *   status: string,
+   *   lastCheckedAt: string|null,
+   *   lastError: string|null,
+   *   callCount: number,
+   *   errorCount: number,
+   *   averageResponseTimeMs: number|null
+   * }}
+   */
+  getStatus() {
+    return {
+      status: this._status,
+      lastCheckedAt: this._lastCheckedAt,
+      lastError: this._lastError,
+      callCount: this._callCount,
+      errorCount: this._errorCount,
+      averageResponseTimeMs:
+        this._successResponseCount > 0 ? this._totalResponseTimeMs / this._successResponseCount : null,
+    };
+  }
+
+  /**
+   * Resets all recorded history back to the initial UNKNOWN state.
+   */
+  reset() {
+    this._status = HealthStatus.UNKNOWN;
+    this._lastCheckedAt = null;
+    this._lastError = null;
+    this._callCount = 0;
+    this._errorCount = 0;
+    this._totalResponseTimeMs = 0;
+    this._successResponseCount = 0;
+  }
+}
+
+export default ProviderHealthMonitor;

package/src/index.js

@@ -0,0 +1,20 @@
+/**
+ * index.js
+ *
+ * Public entry point for the zayra-provider package.
+ *
+ * Anything a consumer needs should be exported from here — they
+ * should never need to import from "zayra-provider/src/...". This
+ * keeps the internal file layout free to change without breaking
+ * zayra-core, zayra-config, zayra-ai-router, or zayra-plugins.
+ */
+
+export { BaseProvider, createProvider, isValidProvider, toRouterProviderPlugin } from "./provider.js";
+export { ProviderRegistry } from "./registry.js";
+export { createLocalProvider } from "./local.js";
+export { normalizeModelInfo, isValidModelInfo } from "./models.js";
+export { ProviderHealthMonitor, HealthStatus } from "./health.js";
+export { getApiKeyFromEnv, resolveApiKey } from "./credentials.js";
+export { ProviderError, AuthenticationError, ConnectionError, ModelError } from "./errors.js";
+
+export { ProviderRegistry as default } from "./registry.js";

package/src/local.js

@@ -0,0 +1,128 @@
+/**
+ * local.js
+ *
+ * Local Provider Support (spec section: "Local Provider Support").
+ * Local runners (Ollama, self-hosted models) don't need API keys and
+ * usually speak HTTP to localhost, but the exact wire format is
+ * specific to whatever runner is in use.
+ *
+ * Rather than hardcoding one local runner's HTTP API (which this
+ * package couldn't verify against a real, running instance from
+ * here, and which would risk shipping an untested integration),
+ * createLocalProvider() takes an injectable `transport` — the actual
+ * chat/generate/model-listing logic your local runner needs — and
+ * wraps it into a conforming Provider. This keeps local support
+ * genuinely testable (inject a fake transport in tests) while still
+ * giving real local runners a ready-made scaffold.
+ */
+
+import { ConnectionError, ProviderError } from "./errors.js";
+import { normalizeModelInfo } from "./models.js";
+
+/**
+ * @typedef {object} LocalTransport
+ * @property {(request: object) => Promise<any>} [chat]
+ * @property {(request: object) => Promise<any>} [generate]
+ * @property {() => Promise<object[]>} [listModels]
+ * @property {() => Promise<boolean>} [ping] - Should resolve true/false, or reject, to indicate reachability.
+ */
+
+/**
+ * Builds a local-runner provider from a caller-supplied transport.
+ *
+ * @example
+ * // Real Ollama wiring (illustrative — not shipped/tested by this package):
+ * const ollama = createLocalProvider({
+ *   name: "local",
+ *   transport: {
+ *     async chat(request) {
+ *       const res = await fetch("http://localhost:11434/api/chat", {
+ *         method: "POST",
+ *         body: JSON.stringify({ model: request.model, messages: request.messages }),
+ *       });
+ *       if (!res.ok) throw new Error(`Ollama returned ${res.status}`);
+ *       return res.json();
+ *     },
+ *     async ping() {
+ *       const res = await fetch("http://localhost:11434/api/tags");
+ *       return res.ok;
+ *     },
+ *   },
+ *   models: [{ name: "llama3", speed: "balanced" }],
+ * });
+ *
+ * @param {object} options
+ * @param {string} options.name
+ * @param {LocalTransport} options.transport
+ * @param {object[]} [options.models] - Static model list, used if transport.listModels isn't provided.
+ * @returns {import("./provider.js").Provider}
+ */
+export function createLocalProvider(options = {}) {
+  const { name, transport, models: staticModels = [] } = options;
+
+  if (typeof name !== "string" || name.length === 0) {
+    throw new ProviderError("createLocalProvider() requires a non-empty string name.");
+  }
+  if (!transport || typeof transport !== "object") {
+    throw new ProviderError(`Local provider "${name}" requires a transport.`, { providerName: name });
+  }
+
+  return {
+    name,
+
+    async models() {
+      const raw = typeof transport.listModels === "function" ? await transport.listModels() : staticModels;
+      return raw.map((m) => normalizeModelInfo(m));
+    },
+
+    async chat(request) {
+      if (typeof transport.chat !== "function") {
+        throw new ProviderError(`Local provider "${name}" transport does not implement chat().`, {
+          providerName: name,
+        });
+      }
+      try {
+        return await transport.chat(request);
+      } catch (err) {
+        throw new ConnectionError(`Local provider "${name}" chat request failed: ${err.message}`, {
+          providerName: name,
+          cause: err,
+        });
+      }
+    },
+
+    async generate(request) {
+      if (typeof transport.generate !== "function") {
+        throw new ProviderError(`Local provider "${name}" transport does not implement generate().`, {
+          providerName: name,
+        });
+      }
+      try {
+        return await transport.generate(request);
+      } catch (err) {
+        throw new ConnectionError(`Local provider "${name}" generate request failed: ${err.message}`, {
+          providerName: name,
+          cause: err,
+        });
+      }
+    },
+
+    async status() {
+      if (typeof transport.ping !== "function") {
+        // No way to check reachability — report unknown rather than
+        // guessing "online".
+        return { status: "unknown", details: "Transport does not implement ping()." };
+      }
+      try {
+        const reachable = await transport.ping();
+        return reachable ? { status: "online" } : { status: "offline" };
+      } catch (err) {
+        return { status: "offline", details: err.message };
+      }
+    },
+  };
+}
+
+export default {
+  createLocalProvider,
+};

package/src/models.js

@@ -0,0 +1,57 @@
+/**
+ * models.js
+ *
+ * Model Information System (spec section: "Model Information
+ * System"). Every provider exposes model metadata through its
+ * models() method; this file defines and normalizes that shape so
+ * every provider reports it consistently: model name, capabilities,
+ * context length, speed, and availability.
+ */
+
+import { ModelError } from "./errors.js";
+
+/**
+ * @typedef {object} ModelInfo
+ * @property {string} name
+ * @property {string[]} capabilities - e.g. ["chat", "coding"]. Empty means general-purpose.
+ * @property {number} [contextLength] - Context window size, in tokens.
+ * @property {"fast"|"balanced"|"slow"} [speed="balanced"]
+ * @property {boolean} [available=true]
+ */
+
+/**
+ * Normalizes a raw model info object (as a provider might return it)
+ * by filling in defaults for optional fields.
+ *
+ * @param {object} raw
+ * @returns {ModelInfo}
+ * @throws {ModelError} If `raw` is missing a name.
+ */
+export function normalizeModelInfo(raw) {
+  if (!raw || typeof raw.name !== "string" || raw.name.length === 0) {
+    throw new ModelError("Model info requires a non-empty string name.");
+  }
+
+  return {
+    name: raw.name,
+    capabilities: Array.isArray(raw.capabilities) ? raw.capabilities : [],
+    contextLength: typeof raw.contextLength === "number" ? raw.contextLength : undefined,
+    speed: raw.speed ?? "balanced",
+    available: raw.available !== undefined ? Boolean(raw.available) : true,
+  };
+}
+
+/**
+ * Returns true if `value` is at least minimally shaped like a
+ * ModelInfo (has a non-empty string name).
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidModelInfo(value) {
+  return typeof value === "object" && value !== null && typeof value.name === "string" && value.name.length > 0;
+}
+
+export default {
+  normalizeModelInfo,
+  isValidModelInfo,
+};

package/src/provider.js

@@ -0,0 +1,204 @@
+/**
+ * provider.js
+ *
+ * Provider Interface System (spec section: "Provider Interface
+ * System"). Defines the standard shape every provider must support:
+ *
+ *   name
+ *   models()
+ *   chat()
+ *   generate()
+ *   status()
+ *
+ * Two ways to build a conforming provider:
+ *   - extend BaseProvider (batteries included: credential resolution helper, clear "not implemented" errors)
+ *   - or hand-roll a plain object with the same five members (validated structurally, not via instanceof)
+ *
+ * Either way, zayra-provider itself never implements a real network
+ * call to any specific AI platform — concrete providers (groq-provider,
+ * gemini-provider, etc.) are separate packages that plug into this
+ * shape, matching the ecosystem's Plugin Compatibility model.
+ */
+
+import { ProviderError } from "./errors.js";
+import { resolveApiKey } from "./credentials.js";
+
+/**
+ * @typedef {object} Provider
+ * @property {string} name
+ * @property {() => Promise<import("./models.js").ModelInfo[]>} models
+ * @property {(request: object) => Promise<any>} chat
+ * @property {(request: object) => Promise<any>} generate
+ * @property {() => Promise<{ status: string, details?: string }>} status
+ */
+
+/**
+ * Returns true if `value` structurally satisfies the Provider shape:
+ * a name, and models()/chat()/generate()/status() functions.
+ *
+ * @param {unknown} value
+ * @returns {boolean}
+ */
+export function isValidProvider(value) {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    typeof value.name === "string" &&
+    value.name.length > 0 &&
+    typeof value.models === "function" &&
+    typeof value.chat === "function" &&
+    typeof value.generate === "function" &&
+    typeof value.status === "function"
+  );
+}
+
+/**
+ * Optional base class for building a provider. Subclasses override
+ * models()/chat()/generate()/status(); the unoverridden defaults
+ * throw a clear ProviderError rather than doing nothing, so a
+ * forgotten method fails loudly during development instead of
+ * silently misbehaving at runtime.
+ *
+ * @example
+ * class MyProvider extends BaseProvider {
+ *   constructor() { super({ name: "my-provider" }); }
+ *   async models() { return [{ name: "my-model" }]; }
+ *   async chat(request) { ... }
+ *   async generate(request) { ... }
+ *   async status() { return { status: "online" }; }
+ * }
+ */
+export class BaseProvider {
+  /**
+   * @param {object} options
+   * @param {string} options.name
+   * @param {string} [options.apiKeyEnvName] - Overrides which env var / config key this provider's credential is looked up under. Defaults to `name`.
+   */
+  constructor(options = {}) {
+    if (typeof options.name !== "string" || options.name.length === 0) {
+      throw new ProviderError("A provider requires a non-empty string name.");
+    }
+
+    this.name = options.name;
+    this._apiKeyEnvName = options.apiKeyEnvName ?? options.name;
+  }
+
+  /**
+   * Resolves this provider's API key on demand — never stored on
+   * `this` or anywhere else in this package. See credentials.js.
+   *
+   * @param {object} [options]
+   * @param {object} [options.config] - A zayra-config-shaped object.
+   * @param {Record<string, string>} [options.env]
+   * @returns {string|undefined}
+   */
+  resolveApiKey(options = {}) {
+    return resolveApiKey(this._apiKeyEnvName, options);
+  }
+
+  /** @returns {Promise<import("./models.js").ModelInfo[]>} */
+  async models() {
+    throw new ProviderError(`Provider "${this.name}" does not implement models().`, { providerName: this.name });
+  }
+
+  /** @param {object} request @returns {Promise<any>} */
+  async chat(_request) {
+    throw new ProviderError(`Provider "${this.name}" does not implement chat().`, { providerName: this.name });
+  }
+
+  /** @param {object} request @returns {Promise<any>} */
+  async generate(_request) {
+    throw new ProviderError(`Provider "${this.name}" does not implement generate().`, { providerName: this.name });
+  }
+
+  /** @returns {Promise<{ status: string, details?: string }>} */
+  async status() {
+    throw new ProviderError(`Provider "${this.name}" does not implement status().`, { providerName: this.name });
+  }
+}
+
+/**
+ * Functional alternative to extending BaseProvider: builds a
+ * conforming provider from plain functions. Useful for quick custom
+ * providers that don't need a full class.
+ *
+ * @param {object} options
+ * @param {string} options.name
+ * @param {() => Promise<object[]>} options.models
+ * @param {(request: object) => Promise<any>} options.chat
+ * @param {(request: object) => Promise<any>} options.generate
+ * @param {() => Promise<{ status: string, details?: string }>} options.status
+ * @returns {Provider}
+ * @throws {ProviderError} If any required member is missing.
+ */
+export function createProvider(options = {}) {
+  const provider = {
+    name: options.name,
+    models: options.models,
+    chat: options.chat,
+    generate: options.generate,
+    status: options.status,
+  };
+
+  if (!isValidProvider(provider)) {
+    throw new ProviderError(
+      'createProvider() requires { name, models, chat, generate, status } — a name and all four functions.'
+    );
+  }
+
+  return provider;
+}
+
+/**
+ * Adapts a zayra-provider Provider into the plugin shape
+ * zayra-ai-router's ProviderRegistry expects ({ name, isAvailable,
+ * listModels, invoke }), so the two packages interoperate without
+ * either one hardcoding knowledge of the other. This is a pure
+ * shape/method translation — it makes no decisions about which
+ * provider or model to use, so it stays within zayra-provider's
+ * "connection only" mandate.
+ *
+ * request.messages present -> delegates to chat(); otherwise -> generate().
+ *
+ * @param {Provider} provider
+ * @returns {{ name: string, isAvailable: () => Promise<boolean>, listModels: () => Promise<object[]>, invoke: (request: object) => Promise<any> }}
+ */
+export function toRouterProviderPlugin(provider) {
+  if (!isValidProvider(provider)) {
+    throw new ProviderError("toRouterProviderPlugin() requires a valid Provider.");
+  }
+
+  return {
+    name: provider.name,
+    async isAvailable() {
+      try {
+        const result = await provider.status();
+        return result?.status === "online";
+      } catch {
+        return false;
+      }
+    },
+    async listModels() {
+      const models = await provider.models();
+      return Array.isArray(models)
+        ? models.map((m) => ({
+            name: m.name,
+            capabilities: m.capabilities ?? [],
+            speed: m.speed ?? "balanced",
+            contextSize: m.contextLength,
+            status: m.available === false ? "unavailable" : "available",
+          }))
+        : [];
+    },
+    async invoke(request) {
+      return Array.isArray(request?.messages) ? provider.chat(request) : provider.generate(request);
+    },
+  };
+}
+
+export default {
+  isValidProvider,
+  BaseProvider,
+  createProvider,
+  toRouterProviderPlugin,
+};

package/src/registry.js

@@ -0,0 +1,199 @@
+/**
+ * registry.js
+ *
+ * Dynamic Provider Registration (spec section: "Dynamic Provider
+ * Registration") + Provider Health Check wiring. Registers providers
+ * at runtime and routes calls through them while automatically
+ * recording health (online/offline, errors, response time) for
+ * every call that goes through the registry.
+ *
+ * Per the package's rules, this never decides *which* provider to
+ * use for a request — every method here takes the provider name as
+ * an explicit argument. Choosing a provider is zayra-ai-router's job.
+ */
+
+import { ProviderError, ConnectionError } from "./errors.js";
+import { isValidProvider } from "./provider.js";
+import { ProviderHealthMonitor } from "./health.js";
+
+/**
+ * Registers and manages Provider instances, and tracks their health.
+ *
+ * @example
+ * const registry = new ProviderRegistry();
+ * registry.register(groqProvider);
+ * await registry.chat("groq", { messages: [...] });
+ * registry.getHealth("groq"); // { status: "online", ... }
+ */
+export class ProviderRegistry {
+  constructor() {
+    /** @type {Map<string, import("./provider.js").Provider>} */
+    this._providers = new Map();
+    /** @type {Map<string, ProviderHealthMonitor>} */
+    this._health = new Map();
+  }
+
+  /**
+   * Registers a provider.
+   * @param {import("./provider.js").Provider} provider
+   * @returns {this}
+   * @throws {ProviderError} If malformed or already registered.
+   */
+  register(provider) {
+    if (!isValidProvider(provider)) {
+      throw new ProviderError(
+        'A provider requires a string "name" and models()/chat()/generate()/status() functions.'
+      );
+    }
+
+    if (this._providers.has(provider.name)) {
+      throw new ProviderError(`Provider "${provider.name}" is already registered.`, { providerName: provider.name });
+    }
+
+    this._providers.set(provider.name, provider);
+    this._health.set(provider.name, new ProviderHealthMonitor());
+    return this;
+  }
+
+  /**
+   * Removes a registered provider and its health history.
+   * @param {string} name
+   * @returns {boolean} True if a provider was removed.
+   */
+  unregister(name) {
+    this._health.delete(name);
+    return this._providers.delete(name);
+  }
+
+  /**
+   * @param {string} name
+   * @returns {import("./provider.js").Provider}
+   * @throws {ProviderError} If not registered.
+   */
+  get(name) {
+    const provider = this._providers.get(name);
+    if (!provider) {
+      throw new ProviderError(`Provider "${name}" is not registered.`, { providerName: name });
+    }
+    return provider;
+  }
+
+  /** @param {string} name @returns {boolean} */
+  has(name) {
+    return this._providers.has(name);
+  }
+
+  /** @returns {string[]} Names of every registered provider. */
+  list() {
+    return [...this._providers.keys()];
+  }
+
+  /**
+   * @param {string} name
+   * @returns {ReturnType<ProviderHealthMonitor["getStatus"]>|null}
+   */
+  getHealth(name) {
+    return this._health.get(name)?.getStatus() ?? null;
+  }
+
+  /** @returns {Array<{ name: string } & ReturnType<ProviderHealthMonitor["getStatus"]>>} */
+  getAllHealth() {
+    return this.list().map((name) => ({ name, ...this.getHealth(name) }));
+  }
+
+  /**
+   * Lists a provider's models. Not health-tracked (model metadata
+   * lookups aren't the primary reliability signal — chat/generate/
+   * status calls are).
+   * @param {string} name
+   * @returns {Promise<import("./models.js").ModelInfo[]>}
+   */
+  async listModels(name) {
+    return this.get(name).models();
+  }
+
+  /**
+   * Calls a provider's status() and records the outcome into its
+   * health history.
+   * @param {string} name
+   * @returns {Promise<{ status: string, details?: string }>}
+   */
+  async checkStatus(name) {
+    return this._callTracked(name, "status", []);
+  }
+
+  /**
+   * Checks every registered provider's status, tolerant of
+   * individual failures (one provider being down doesn't stop the
+   * others from being checked).
+   * @returns {Promise<Array<{ name: string, status: string, details?: string, error?: string }>>}
+   */
+  async checkAllStatus() {
+    return Promise.all(
+      this.list().map(async (name) => {
+        try {
+          const result = await this.checkStatus(name);
+          return { name, ...result };
+        } catch (err) {
+          return { name, status: "offline", error: err.message };
+        }
+      })
+    );
+  }
+
+  /**
+   * Sends a chat request to a specific provider, with health tracking.
+   * @param {string} name
+   * @param {object} request
+   * @returns {Promise<any>}
+   */
+  async chat(name, request) {
+    return this._callTracked(name, "chat", [request]);
+  }
+
+  /**
+   * Sends a generate request to a specific provider, with health tracking.
+   * @param {string} name
+   * @param {object} request
+   * @returns {Promise<any>}
+   */
+  async generate(name, request) {
+    return this._callTracked(name, "generate", [request]);
+  }
+
+  /**
+   * Calls `provider[method](...args)`, timing it and recording the
+   * outcome into that provider's health monitor.
+   *
+   * @param {string} name
+   * @param {"chat"|"generate"|"status"} method
+   * @param {any[]} args
+   * @returns {Promise<any>}
+   * @private
+   */
+  async _callTracked(name, method, args) {
+    const provider = this.get(name);
+    const health = this._health.get(name);
+    const startedAt = Date.now();
+
+    try {
+      const result = await provider[method](...args);
+      health.recordSuccess(Date.now() - startedAt);
+      return result;
+    } catch (err) {
+      health.recordFailure(err);
+      // Re-throw as-is if it's already one of this package's typed
+      // errors (AuthenticationError/ConnectionError/ModelError/
+      // ProviderError) — only wrap genuinely unknown failures.
+      if (err instanceof ProviderError) {
+        throw err;
+      }
+      throw new ConnectionError(`Provider "${name}" ${method}() failed: ${err.message}`, {
+        providerName: name,
+        cause: err,
+      });
+    }
+  }
+}
+
+export default ProviderRegistry;