adapt-api 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Pankaj Kumar Jain and Jahnavi Thirumalasetty
+
+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,75 @@
+# adapt-api
+
+Production-oriented Node.js CLI for ADAPT API readiness assessment.
+
+## Features
+
+- `config` command for persistent defaults (`llm`, `model`, `format`, `api key`, `base url`)
+- `eval <file_path>` command to assess OpenAPI/RAML files
+- Modular ADAPT engine (spec loading, heuristic checks, LLM evaluation, disposition rules)
+- Output factory for `json`, `text`, or `pdf`
+- Spinner-based progress with `ora`
+- Local config persistence via `conf` in the user config directory
+
+## Install
+
+From npm (after publish):
+
+```bash
+npm install -g adapt-api
+```
+
+For local development:
+
+```bash
+npm install
+```
+
+For local command testing:
+
+```bash
+npm link
+```
+
+## Usage
+
+### Configure defaults
+
+```bash
+apiadapt config --llm openai --model gpt-4o-mini --format json --api-key <key>
+```
+
+Or interactive:
+
+```bash
+apiadapt config
+```
+
+### Evaluate a spec
+
+```bash
+apiadapt eval ./openapi.yaml
+```
+
+Write explicit output:
+
+```bash
+apiadapt eval ./openapi.yaml --format pdf --output ./report.pdf
+```
+
+Print output to terminal:
+
+```bash
+apiadapt eval ./openapi.yaml --format text --print
+```
+
+## Commands
+
+- `apiadapt config [--llm] [--model] [--format] [--api-key] [--base-url]`
+- `apiadapt eval <file_path> [--format] [--output] [--print]`
+
+## Notes
+
+- OpenAI and Anthropic providers require an API key (`--api-key` in config).
+- Ollama defaults to `http://localhost:11434`; override with `--base-url`.
+- If LLM evaluation fails, the CLI falls back to heuristic assessment and still returns output.

package/bin/apiadapt.js

@@ -0,0 +1,9 @@
+#!/usr/bin/env node
+
+import { runCli } from "../src/cli.js";
+
+runCli(process.argv).catch((error) => {
+  const message = error?.message || "Unknown error";
+  process.stderr.write(`apiadapt: ${message}\n`);
+  process.exitCode = 1;
+});

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "adapt-api",
+  "version": "1.0.0",
+  "description": "ADAPT API readiness assessment CLI",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://www.npmjs.com/package/adapt-api",
+  "bugs": {
+    "url": "https://www.npmjs.com/package/adapt-api"
+  },
+  "bin": {
+    "apiadapt": "./bin/apiadapt.js"
+  },
+  "files": [
+    "bin/",
+    "src/",
+    "README.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "start": "node ./bin/apiadapt.js",
+    "verify": "node ./bin/apiadapt.js --help && node ./bin/apiadapt.js manual > /dev/null",
+    "prepublishOnly": "npm run verify"
+  },
+  "keywords": [
+    "cli",
+    "adapt",
+    "openapi",
+    "raml",
+    "assessment"
+  ],
+  "engines": {
+    "node": ">=18.17.0"
+  },
+  "dependencies": {
+    "commander": "^14.0.1",
+    "conf": "^14.0.0",
+    "fs-extra": "^11.3.2",
+    "js-yaml": "^4.1.0",
+    "ora": "^9.0.0",
+    "pdfkit": "^0.17.2"
+  }
+}

package/src/cli.js

@@ -0,0 +1,57 @@
+import { Command } from "commander";
+import { runConfigCommand } from "./commands/config.js";
+import { runEvalCommand } from "./commands/eval.js";
+import { runManualCommand } from "./commands/manual.js";
+
+export async function runCli(argv) {
+  const program = new Command();
+
+  program
+    .name("apiadapt")
+    .description("ADAPT engine CLI for API readiness assessments")
+    .version("1.0.0");
+  program.addHelpText(
+    "after",
+    `
+Quick examples:
+  apiadapt manual
+  apiadapt config --llm ollama --model llama3.2 --format text
+  apiadapt config --llm openai --model gpt-4o-mini --api-key <OPENAI_KEY> --format json
+  apiadapt eval ./openapi.yaml --format json --output ./report.json
+  apiadapt eval ./openapi.yaml --format pdf --output ./assessment.pdf
+`,
+  );
+
+  program
+    .command("config")
+    .description("Set default LLM provider/model/output format")
+    .option("--llm <provider>", "LLM provider: ollama|openai|anthropic")
+    .option("--model <name>", "Model name for provider")
+    .option("--format <type>", "Default output format: json|text|pdf")
+    .option("--api-key <key>", "Provider API key (for openai/anthropic)")
+    .option("--base-url <url>", "Custom provider base URL")
+    .action(async (options) => {
+      await runConfigCommand(options);
+    });
+
+  program
+    .command("eval")
+    .description("Evaluate an API spec file with ADAPT engine")
+    .argument("<file_path>", "Path to OpenAPI/RAML file")
+    .option("--output <path>", "Output path (writes file when set)")
+    .option("--format <type>", "Output format: json|text|pdf")
+    .option("--print", "Print result to stdout", false)
+    .action(async (filePath, options) => {
+      await runEvalCommand(filePath, options);
+    });
+
+  program
+    .command("manual")
+    .alias("man")
+    .description("Show detailed command guide with examples")
+    .action(() => {
+      runManualCommand();
+    });
+
+  await program.parseAsync(argv);
+}

package/src/commands/config.js

@@ -0,0 +1,48 @@
+import { askQuestion } from "../utils/prompts.js";
+import { getConfigPath, getSettings, saveSettings } from "../utils/configStore.js";
+
+export async function runConfigCommand(options) {
+  const current = getSettings();
+  const fromFlags = {
+    llmProvider: options.llm,
+    model: options.model,
+    outputFormat: options.format,
+    apiKey: options.apiKey,
+    baseUrl: options.baseUrl,
+  };
+
+  const hasFlags = Object.values(fromFlags).some((v) => v !== undefined);
+
+  let finalConfig = fromFlags;
+  if (!hasFlags) {
+    const llmProvider = await askQuestion(
+      `LLM provider [ollama/openai/anthropic] (${current.llmProvider}): `,
+      current.llmProvider,
+    );
+    const model = await askQuestion(`Model (${current.model}): `, current.model);
+    const outputFormat = await askQuestion(
+      `Default format [text/json/pdf] (${current.outputFormat}): `,
+      current.outputFormat,
+    );
+    const apiKey = await askQuestion(
+      "API key (leave blank to keep current): ",
+      current.apiKey,
+    );
+    const baseUrl = await askQuestion(
+      "Base URL (leave blank for provider default): ",
+      current.baseUrl,
+    );
+    finalConfig = { llmProvider, model, outputFormat, apiKey, baseUrl };
+  }
+
+  const saved = saveSettings(finalConfig);
+  process.stdout.write(
+    [
+      "Configuration saved.",
+      `Config file: ${getConfigPath()}`,
+      `Provider: ${saved.llmProvider}`,
+      `Model: ${saved.model}`,
+      `Default format: ${saved.outputFormat}`,
+    ].join("\n") + "\n",
+  );
+}

package/src/commands/eval.js

@@ -0,0 +1,39 @@
+import ora from "ora";
+import {
+  defaultOutputPath,
+  renderOutput,
+  writeOutputFile,
+} from "../formatters/index.js";
+import { evaluateSpecFile } from "../engine/evaluator.js";
+import { getSettings } from "../utils/configStore.js";
+
+export async function runEvalCommand(filePath, options) {
+  const settings = getSettings();
+  const outputFormat = String(options.format || settings.outputFormat || "text").toLowerCase();
+  const spinner = ora("Running ADAPT assessment...").start();
+
+  let report;
+  try {
+    report = await evaluateSpecFile(filePath, settings);
+    spinner.succeed(`Assessment complete: ${report.assessment.disposition}`);
+  } catch (error) {
+    spinner.fail("Assessment failed.");
+    throw error;
+  }
+
+  const payload = await renderOutput(report, outputFormat);
+  const shouldPrint = Boolean(options.print) || (!options.output && outputFormat !== "pdf");
+  if (shouldPrint) {
+    if (payload.isBinary) {
+      process.stdout.write("PDF output is binary; provide --output to save file.\n");
+    } else {
+      process.stdout.write(payload.content);
+    }
+  }
+
+  if (options.output || outputFormat === "pdf") {
+    const outputPath = options.output || defaultOutputPath(filePath, outputFormat);
+    await writeOutputFile(outputPath, payload);
+    process.stdout.write(`Saved output to: ${outputPath}\n`);
+  }
+}

package/src/commands/manual.js

@@ -0,0 +1,57 @@
+export function runManualCommand() {
+  const manual = `
+apiadapt manual
+==============
+
+Overview
+--------
+apiadapt evaluates OpenAPI/RAML specs for ADAPT readiness.
+
+Core Commands
+-------------
+1) Configure defaults
+   apiadapt config [--llm <provider>] [--model <name>] [--format <text|json|pdf>] [--api-key <key>] [--base-url <url>]
+
+2) Evaluate a spec
+   apiadapt eval <file_path> [--format <text|json|pdf>] [--output <path>] [--print]
+
+How to Configure LLM + Model
+----------------------------
+Use ollama (local):
+  apiadapt config --llm ollama --model llama3.2 --format text
+  # Optional custom host:
+  apiadapt config --llm ollama --model llama3.2 --base-url http://localhost:11434
+
+Use OpenAI:
+  apiadapt config --llm openai --model gpt-4o-mini --api-key <OPENAI_API_KEY> --format json
+  # Optional custom endpoint:
+  apiadapt config --llm openai --model gpt-4o --base-url https://api.openai.com
+
+Use Anthropic:
+  apiadapt config --llm anthropic --model claude-3-5-sonnet-latest --api-key <ANTHROPIC_API_KEY> --format json
+  # Optional custom endpoint:
+  apiadapt config --llm anthropic --model claude-3-5-sonnet-latest --base-url https://api.anthropic.com
+
+Run Evaluations
+---------------
+Print text to terminal:
+  apiadapt eval ./openapi.yaml --format text --print
+
+Save JSON report:
+  apiadapt eval ./openapi.yaml --format json --output ./reports/adapt-report.json
+
+Save PDF report:
+  apiadapt eval ./openapi.yaml --format pdf --output ./reports/adapt-report.pdf
+
+Use stored defaults (no extra flags):
+  apiadapt eval ./openapi.yaml
+
+Tips
+----
+- Run "apiadapt config" with no flags for interactive setup.
+- Use "apiadapt --help" for short help.
+- Use "apiadapt manual" for full guide and examples.
+`;
+
+  process.stdout.write(manual);
+}

package/src/engine/SystemPrompt.txt

@@ -0,0 +1,77 @@
+You are an expert Enterprise API Architect and an AI Agent Evaluator. Your task is to analyze OpenAPI or RAML specifications and assess their readiness for Generative AI agent consumption using the protocol-agnostic Agent-Driven API Assessment and Transformation (ADAPT) framework.
+
+Your entire reply must be exactly one JSON object—no other text, no markdown, no bullet points, no section headers (e.g. no "Pillar 1: Interpretability"), no prose. Responses that are not valid JSON will be rejected.
+
+You must evaluate the provided API specification against 4 Pillars, 17 Constructs (five under Interpretability, Operability, and Governance; two under Performance & Economics), and identify applicable gaps from the ADAPT taxonomy of twenty named deficiency types.
+
+# THE ADAPT FRAMEWORK EVALUATION CRITERIA
+
+## Pillar 1: Interpretability
+Check if the agent can understand what this API does. Look for:
+* I-01: Semantic Opacity — vague endpoint names, missing descriptions, or unclear parameter purposes (classify severity from evidence in the spec).
+* I-02: Discovery Blindness (Severity: Major) — lack of proper tags, missing entry points, or unlinked operations.
+* I-03: Schema Permissiveness (Severity: Critical when schemas are clearly underspecified) — missing strict data types, lack of enums, or overly broad formats causing hallucination risk.
+* I-04: Spec-Reality Divergence (Severity: Critical when evidence is strong) — indications the spec may not match runtime behavior (e.g., catch-all/proxy paths, known parser-invalid composition).
+* I-05: Intent Misalignment (Severity: Major) — under Intent-Oriented Design: the contract makes it hard for an agent to infer the correct task-level goal or to map user intent to the right operations (e.g., misleading summaries, verb/noun semantics at odds with behavior, generic CRUD surfaces that obscure real business actions, operations grouped or named such that tool selection would systematically misfire).
+
+## Pillar 2: Operability
+Check if the agent can invoke this API safely and reliably. Look for:
+* O-01: Non-Idempotency Exposure (Severity: Critical) — destructive or mutating operations lacking idempotency keys or safe retry mechanisms.
+* O-02: Response Inconsistency (Severity: Major) — varying return shapes or unpredictable payload structures.
+* O-03: Opaque Error Signaling (Severity: Major) — generic errors without standardized, machine-readable codes or mitigations.
+* O-04: Stateful Session Dependency (Severity: Critical / Override) — reliance on cookies, sticky sessions, MQTT/event connection state, or multi-step stateful flows rather than stateless token-style access.
+* O-05: Operation Dependency Opacity (Severity: Major) — hidden prerequisites (e.g., endpoint A before B) not documented in the spec.
+
+## Pillar 3: Governance
+Check if the agent can be safely controlled, audited, or governed. Look for:
+* G-01: Authorization Opacity (Severity: from evidence) — unclear or complex auth schemes not suited to standard agent tool calling.
+* G-02: Human Approval Bypass Risk (Severity: Critical / Override) — high-stakes operations without documented approval, confirmation, or safeguard when the spec implies such risk.
+* G-03: Observability Absence (Severity: Major) — missing correlation IDs or tracking headers for audit trails.
+* G-04: Version Instability (Severity: Major) — unclear versioning risking agent breakage on updates.
+* G-05: Regulated Data Exposure (Severity: Critical) — unfiltered PII, PCI, or PHI in responses.
+* G-06: Excessive Permission Surface (Severity: Critical) — coarse-grained scopes instead of least-privilege agent scopes.
+* G-07: Prompt Injection Susceptibility (Severity: Critical) — raw user input fields passed to sensitive execution without validation.
+
+## Pillar 4: Performance & Economics
+Check if the agent can operate within practical constraints. Look for:
+* P-01: Context Window Overflow (Severity: Major) — oversized payloads, missing pagination, or missing filters that can overwhelm context.
+* P-02: Cost Opacity (Severity: Major) — missing rate-limit or cost signals.
+* P-03: Infrastructure Fragility (Severity: Critical) — shared legacy backends with no isolation path for high-velocity agent traffic.
+
+# SEVERITY AND OVERRIDE DISCIPLINE
+- Use Critical only with clear evidence in the spec; prefer Major or Minor when uncertain.
+- O-04: Report when the spec documents cookie/session auth, broker persistence, or other session-like coupling that conflicts with stateless agent invocation. For cookie-only specs, report O-04 with overrides_disposition true and avoid piling on redundant Criticals for the same session issue alone.
+- G-02: Report only for clearly high-impact operations lacking documented safeguards—not routine CRUD.
+- I-04: Report for catch-all/proxy segments or strong hints the contract does not match behavior.
+- I-05: Report when naming, descriptions, or operation grouping suggest an agent would mis-select tools or misunderstand what each operation is for relative to likely user tasks—not mere missing prose where I-01 applies.
+- G-07: Report when fields suggest unvalidated execution (e.g. system_command_override, raw_command, exec_payload).
+
+# DISPOSITION LOGIC (for your reasoning; the server recomputes disposition from gaps)
+The assessment assigns one of five transformation dispositions:
+1. Agent-Ready: Zero Critical, Zero Major, only Minor gaps with no operational-monitoring concern.
+2. Expose and Monitor: Zero Critical, Zero Major, Minor gaps that warrant monitoring (e.g. payment workflows, implicit dependencies, undocumented rate limits).
+3. Fix & Expose: Zero Critical, Major gaps only, addressable via specification enrichment; Majors limited and confined to Interpretability or Performance & Economics per rules engine.
+4. Wrap & Expose: Override gaps (O-04, G-02), Major count threshold, Critical in Operability or Governance, or other wrap rules.
+5. Rebuild for Agents: Critical gaps in three or more pillars simultaneously, or Critical P-03 on a shared backend without isolation.
+
+Set root-level "minor_operational_risk" to true only when Critical and Major counts are both zero, at least one Minor gap is present, and some Minor gap(s) imply operational monitoring (financial/approval workflows, undocumented limits, risky implicit ordering). Otherwise false.
+
+# OUTPUT FORMAT (STRICT, JSON-ONLY)
+Your entire response must be exactly one JSON object. Any other format will be rejected.
+
+- Do NOT use markdown, code fences, headers, or prose outside the JSON.
+- The response MUST be strict JSON, ideally one line.
+- Root object fields:
+  - "pillars": exactly ["Interpretability", "Operability", "Governance", "Performance & Economics"]
+  - "minor_operational_risk": boolean
+  - "gaps": array of {"gap_id": "X-NN", "description": "...", "pillar": "...", "severity": "Critical|Major|Minor", "overrides_disposition": false}
+- Override: overrides_disposition true ONLY for O-04 and G-02 when those gaps are reported.
+
+- If truly no ADAPT gaps apply, return:
+  {"pillars": ["Interpretability", "Operability", "Governance", "Performance & Economics"], "minor_operational_risk": false, "gaps": []}
+
+Example (one gap, Major):
+{"pillars": ["Interpretability", "Operability", "Governance", "Performance & Economics"], "minor_operational_risk": false, "gaps": [{"gap_id": "I-01", "description": "Vague naming", "pillar": "Interpretability", "severity": "Major", "overrides_disposition": false}]}
+
+Example (two Majors, Fix & Expose path):
+{"pillars": ["Interpretability", "Operability", "Governance", "Performance & Economics"], "minor_operational_risk": false, "gaps": [{"gap_id": "I-02", "description": "Lack of tags or entry points", "pillar": "Interpretability", "severity": "Major", "overrides_disposition": false}, {"gap_id": "P-01", "description": "List endpoint has no pagination", "pillar": "Performance & Economics", "severity": "Major", "overrides_disposition": false}]}

package/src/engine/disposition.js

@@ -0,0 +1,105 @@
+const OVERRIDE_GAP_IDS = new Set(["O-04", "G-02"]);
+
+function normalizeGaps(gaps) {
+  return (gaps || []).map((g) => ({
+    gap_id: String(g.gap_id || g.id || "").trim().toUpperCase(),
+    severity: String(g.severity || "Minor").trim(),
+    pillar: String(g.pillar || "").trim(),
+    description: String(g.description || ""),
+    overrides_disposition: Boolean(g.overrides_disposition),
+  }));
+}
+
+function countBySeverity(gaps) {
+  let critical = 0;
+  let major = 0;
+  let minor = 0;
+  for (const gap of gaps) {
+    const sev = gap.severity.toLowerCase();
+    if (sev === "critical") critical += 1;
+    else if (sev === "major") major += 1;
+    else minor += 1;
+  }
+  return { critical, major, minor };
+}
+
+function criticalPillars(gaps) {
+  const pillars = new Set();
+  for (const gap of gaps) {
+    if (gap.severity.toLowerCase() === "critical") {
+      pillars.add(gap.pillar);
+    }
+  }
+  return pillars;
+}
+
+function hasOverrideGaps(gaps) {
+  return gaps.some(
+    (gap) => OVERRIDE_GAP_IDS.has(gap.gap_id) || gap.overrides_disposition,
+  );
+}
+
+function hasCriticalOperabilityOrGovernance(gaps) {
+  const target = new Set(["Operability", "Governance"]);
+  return gaps.some(
+    (gap) => gap.severity.toLowerCase() === "critical" && target.has(gap.pillar),
+  );
+}
+
+function majorOnlyIP(gaps) {
+  const allowed = new Set(["Interpretability", "Performance & Economics"]);
+  for (const gap of gaps) {
+    if (gap.severity.toLowerCase() !== "major") continue;
+    if (!allowed.has(gap.pillar)) return false;
+  }
+  return true;
+}
+
+function hasP03Critical(gaps) {
+  return gaps.some(
+    (gap) => gap.gap_id === "P-03" && gap.severity.toLowerCase() === "critical",
+  );
+}
+
+export function computeDisposition(rawGaps, minorOperationalRisk = false) {
+  const gaps = normalizeGaps(rawGaps);
+  const { critical, major, minor } = countBySeverity(gaps);
+  const cPillars = criticalPillars(gaps);
+
+  if (cPillars.size >= 3 || hasP03Critical(gaps)) {
+    return "Rebuild for Agents";
+  }
+  if (hasOverrideGaps(gaps) || major >= 3 || hasCriticalOperabilityOrGovernance(gaps)) {
+    return "Wrap & Expose";
+  }
+  if (critical === 0 && major === 0) {
+    return minor > 0 && minorOperationalRisk ? "Expose and Monitor" : "Agent-Ready";
+  }
+  if (critical === 0 && major <= 2 && majorOnlyIP(gaps)) {
+    return "Fix & Expose";
+  }
+  if (critical === 0 && major <= 2) {
+    return "Fix & Expose";
+  }
+  return "Wrap & Expose";
+}
+
+export function computeDispositionSummary(rawGaps, disposition) {
+  const gaps = normalizeGaps(rawGaps);
+  const { critical, major, minor } = countBySeverity(gaps);
+  let reason = "risk posture aligns with current ADAPT findings";
+
+  if (disposition === "Rebuild for Agents") {
+    reason = "critical gaps are broad enough to require structural rework";
+  } else if (disposition === "Wrap & Expose") {
+    reason = "gap profile requires a protective wrapper before agent exposure";
+  } else if (disposition === "Fix & Expose") {
+    reason = "critical risk is absent and major issues are fixable in place";
+  } else if (disposition === "Expose and Monitor") {
+    reason = "only minor gaps exist, but they require active monitoring";
+  } else if (disposition === "Agent-Ready") {
+    reason = "no blocking critical or major gaps were detected";
+  }
+
+  return `Disposition is ${disposition} because ${reason}. Observed ${critical} critical, ${major} major, and ${minor} minor gaps.`;
+}

package/src/engine/evaluator.js

@@ -0,0 +1,53 @@
+import { loadSpecFromFile } from "../utils/specLoader.js";
+import { runStaticHeuristics } from "./heuristics.js";
+import { evaluateWithLlm } from "./llmClients.js";
+import { computeDisposition, computeDispositionSummary } from "./disposition.js";
+
+export async function evaluateSpecFile(filePath, settings) {
+  const startedAt = Date.now();
+  const spec = await loadSpecFromFile(filePath);
+
+  let assessment = runStaticHeuristics(spec.parsed);
+  let llmError = "";
+
+  try {
+    const llmAssessment = await evaluateWithLlm(settings, spec.rawText);
+    if (Array.isArray(llmAssessment?.gaps) && llmAssessment.gaps.length > 0) {
+      assessment = llmAssessment;
+    } else {
+      assessment.notes = llmAssessment?.notes || assessment.notes;
+      assessment.raw_llm_response = llmAssessment?.raw_llm_response || "";
+    }
+  } catch (error) {
+    llmError = error.message;
+    assessment.notes = `${assessment.notes} LLM call failed: ${llmError}`.trim();
+  }
+
+  const disposition = computeDisposition(
+    assessment.gaps,
+    Boolean(assessment.minor_operational_risk),
+  );
+  const summary = computeDispositionSummary(assessment.gaps, disposition);
+
+  return {
+    spec: {
+      filePath: spec.filePath,
+      fileName: spec.fileName,
+      specType: spec.specType,
+      sizeBytes: spec.sizeBytes,
+      sizeKb: Number((spec.sizeBytes / 1024).toFixed(2)),
+    },
+    assessment: {
+      ...assessment,
+      disposition,
+      summary,
+    },
+    meta: {
+      provider: settings.llmProvider,
+      model: settings.model,
+      generatedAt: new Date().toISOString(),
+      durationMs: Date.now() - startedAt,
+      llmError,
+    },
+  };
+}

package/src/engine/heuristics.js

@@ -0,0 +1,73 @@
+const PILLARS = [
+  "Interpretability",
+  "Operability",
+  "Governance",
+  "Performance & Economics",
+];
+
+function addGap(gaps, gap) {
+  gaps.push({
+    gap_id: gap.gap_id,
+    description: gap.description,
+    pillar: gap.pillar,
+    severity: gap.severity,
+    overrides_disposition: Boolean(gap.overrides_disposition),
+  });
+}
+
+export function runStaticHeuristics(parsedSpec) {
+  const gaps = [];
+  const info = parsedSpec?.info || {};
+  const paths = parsedSpec?.paths || {};
+  const security = parsedSpec?.security || [];
+  const servers = parsedSpec?.servers || [];
+
+  if (!info.title || !info.description) {
+    addGap(gaps, {
+      gap_id: "I-01",
+      pillar: "Interpretability",
+      severity: "Major",
+      description:
+        "API metadata is incomplete. Include clear title and description for agent context.",
+    });
+  }
+
+  if (Object.keys(paths).length === 0) {
+    addGap(gaps, {
+      gap_id: "I-03",
+      pillar: "Interpretability",
+      severity: "Critical",
+      description: "No API paths were found. Agents cannot discover callable operations.",
+    });
+  }
+
+  if (!Array.isArray(security) || security.length === 0) {
+    addGap(gaps, {
+      gap_id: "G-01",
+      pillar: "Governance",
+      severity: "Major",
+      description:
+        "No global security requirement found. Define auth expectations to reduce misuse risk.",
+    });
+  }
+
+  if (!Array.isArray(servers) || servers.length === 0) {
+    addGap(gaps, {
+      gap_id: "O-02",
+      pillar: "Operability",
+      severity: "Minor",
+      description:
+        "No server environment declared. Add server definitions to improve runtime portability.",
+    });
+  }
+
+  return {
+    pillars: PILLARS,
+    minor_operational_risk: gaps.some((g) => g.severity === "Minor"),
+    gaps,
+    notes:
+      "Heuristic-only assessment. Configure an LLM provider for a full ADAPT semantic evaluation.",
+  };
+}
+
+export { PILLARS };

package/src/engine/llmClients.js

@@ -0,0 +1,184 @@
+import { PILLARS } from "./heuristics.js";
+import { readFileSync } from "node:fs";
+
+const SYSTEM_PROMPT = readFileSync(
+  new URL("./SystemPrompt.txt", import.meta.url),
+  "utf8",
+);
+
+function safeJsonParse(text) {
+  try {
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+}
+
+function parseJsonFromText(text) {
+  const direct = safeJsonParse(text);
+  if (direct) return direct;
+
+  const codeBlockMatch = text.match(/```(?:json)?\s*([\s\S]*?)```/i);
+  if (codeBlockMatch?.[1]) {
+    const blockParsed = safeJsonParse(codeBlockMatch[1].trim());
+    if (blockParsed) return blockParsed;
+  }
+
+  const start = text.indexOf("{");
+  const end = text.lastIndexOf("}");
+  if (start >= 0 && end > start) {
+    const sliced = text.slice(start, end + 1);
+    return safeJsonParse(sliced);
+  }
+  return null;
+}
+
+function normalizeAssessment(obj, rawResponse = "") {
+  const gapsRaw = Array.isArray(obj?.gaps) ? obj.gaps : [];
+  const gaps = gapsRaw
+    .filter((g) => g && typeof g === "object")
+    .map((g) => ({
+      gap_id: String(g.gap_id || "GAP-UNK").toUpperCase(),
+      description: String(g.description || ""),
+      pillar: String(g.pillar || "Interpretability"),
+      severity: String(g.severity || "Minor"),
+      overrides_disposition: Boolean(g.overrides_disposition),
+    }));
+
+  const minorOperationalRisk =
+    typeof obj?.minor_operational_risk === "string"
+      ? ["true", "1", "yes"].includes(obj.minor_operational_risk.toLowerCase())
+      : Boolean(obj?.minor_operational_risk);
+
+  const notes =
+    typeof obj?.notes === "string" && obj.notes.trim()
+      ? obj.notes.trim()
+      : gaps.length === 0
+        ? "LLM response did not produce valid ADAPT gaps; empty gap list returned."
+        : "";
+
+  return {
+    pillars: PILLARS,
+    gaps,
+    minor_operational_risk: minorOperationalRisk,
+    notes,
+    raw_llm_response: rawResponse || "",
+  };
+}
+
+async function requestJson(url, payload, headers) {
+  const timeoutMs = Number(process.env.APIADAPT_LLM_TIMEOUT_MS || 20000);
+  let response;
+  try {
+    response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "content-type": "application/json",
+        ...headers,
+      },
+      body: JSON.stringify(payload),
+      signal: AbortSignal.timeout(timeoutMs),
+    });
+  } catch (error) {
+    if (error?.name === "TimeoutError") {
+      throw new Error(`LLM request timed out after ${timeoutMs}ms.`);
+    }
+    throw error;
+  }
+
+  if (!response.ok) {
+    const text = await response.text();
+    throw new Error(`LLM request failed (${response.status}): ${text.slice(0, 300)}`);
+  }
+
+  return response.json();
+}
+
+async function runOllama(model, specText, baseUrl) {
+  const url = `${(baseUrl || "http://localhost:11434").replace(/\/$/, "")}/api/chat`;
+  const data = await requestJson(
+    url,
+    {
+      model,
+      stream: false,
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: specText.slice(0, 12000) },
+      ],
+      options: { temperature: 0 },
+    },
+    {},
+  );
+
+  const content = String(data?.message?.content || "");
+  const parsed = parseJsonFromText(content);
+  return normalizeAssessment(parsed, content);
+}
+
+async function runOpenAI(model, specText, apiKey, baseUrl) {
+  if (!apiKey) {
+    throw new Error("Missing OpenAI API key. Set via `apiadapt config --api-key`.");
+  }
+  const url = `${(baseUrl || "https://api.openai.com").replace(/\/$/, "")}/v1/chat/completions`;
+  const data = await requestJson(
+    url,
+    {
+      model,
+      temperature: 0,
+      response_format: { type: "json_object" },
+      messages: [
+        { role: "system", content: SYSTEM_PROMPT },
+        { role: "user", content: specText.slice(0, 24000) },
+      ],
+    },
+    { Authorization: `Bearer ${apiKey}` },
+  );
+
+  const content = String(data?.choices?.[0]?.message?.content || "");
+  const parsed = parseJsonFromText(content);
+  return normalizeAssessment(parsed, content);
+}
+
+async function runAnthropic(model, specText, apiKey, baseUrl) {
+  if (!apiKey) {
+    throw new Error("Missing Anthropic API key. Set via `apiadapt config --api-key`.");
+  }
+  const url = `${(baseUrl || "https://api.anthropic.com").replace(/\/$/, "")}/v1/messages`;
+  const data = await requestJson(
+    url,
+    {
+      model,
+      max_tokens: 1800,
+      temperature: 0,
+      system: SYSTEM_PROMPT,
+      messages: [{ role: "user", content: specText.slice(0, 24000) }],
+    },
+    {
+      "x-api-key": apiKey,
+      "anthropic-version": "2023-06-01",
+    },
+  );
+
+  const content = Array.isArray(data?.content)
+    ? String(data.content.find((item) => item.type === "text")?.text || "")
+    : "";
+  const parsed = parseJsonFromText(content);
+  return normalizeAssessment(parsed, content);
+}
+
+export async function evaluateWithLlm(settings, specText) {
+  const provider = String(settings.llmProvider || "").toLowerCase();
+  const model = settings.model || "llama3.2";
+
+  if (provider === "ollama") {
+    return runOllama(model, specText, settings.baseUrl);
+  }
+  if (provider === "openai") {
+    return runOpenAI(model, specText, settings.apiKey, settings.baseUrl);
+  }
+  if (provider === "anthropic") {
+    return runAnthropic(model, specText, settings.apiKey, settings.baseUrl);
+  }
+
+  throw new Error(`Unsupported LLM provider "${settings.llmProvider}".`);
+}

package/src/formatters/index.js

@@ -0,0 +1,36 @@
+import path from "node:path";
+import fs from "fs-extra";
+import { formatJson } from "./jsonFormatter.js";
+import { formatText } from "./textFormatter.js";
+import { formatPdf } from "./pdfFormatter.js";
+
+function extensionFor(format) {
+  if (format === "json") return ".json";
+  if (format === "pdf") return ".pdf";
+  return ".txt";
+}
+
+export function defaultOutputPath(inputFilePath, format) {
+  const parsed = path.parse(inputFilePath);
+  return path.join(parsed.dir, `${parsed.name}.adapt-report${extensionFor(format)}`);
+}
+
+export async function renderOutput(report, format) {
+  const normalized = String(format || "text").toLowerCase();
+  if (normalized === "json") {
+    return { content: formatJson(report), isBinary: false };
+  }
+  if (normalized === "pdf") {
+    return { content: await formatPdf(report), isBinary: true };
+  }
+  return { content: formatText(report), isBinary: false };
+}
+
+export async function writeOutputFile(outputPath, payload) {
+  await fs.ensureDir(path.dirname(outputPath));
+  if (payload.isBinary) {
+    await fs.writeFile(outputPath, payload.content);
+  } else {
+    await fs.writeFile(outputPath, payload.content, "utf8");
+  }
+}

package/src/formatters/jsonFormatter.js

@@ -0,0 +1,3 @@
+export function formatJson(report) {
+  return JSON.stringify(report, null, 2);
+}

package/src/formatters/pdfFormatter.js

@@ -0,0 +1,48 @@
+import PDFDocument from "pdfkit";
+
+function collectPdfBuffer(doc) {
+  return new Promise((resolve, reject) => {
+    const chunks = [];
+    doc.on("data", (chunk) => chunks.push(chunk));
+    doc.on("end", () => resolve(Buffer.concat(chunks)));
+    doc.on("error", reject);
+  });
+}
+
+export async function formatPdf(report) {
+  const doc = new PDFDocument({ size: "LETTER", margin: 50 });
+  const bufferPromise = collectPdfBuffer(doc);
+
+  doc.fontSize(18).text("ADAPT API Assessment Report");
+  doc.moveDown(0.5);
+  doc.fontSize(11).text(`Date: ${new Date(report.meta.generatedAt).toISOString()}`);
+  doc.text(`Spec: ${report.spec.fileName}`);
+  doc.text(`Type: ${report.spec.specType}`);
+  doc.text(`Disposition: ${report.assessment.disposition}`);
+  doc.moveDown(0.5);
+  doc.fontSize(12).text("Summary", { underline: true });
+  doc.fontSize(10).text(report.assessment.summary || "No summary.");
+  doc.moveDown(0.5);
+  doc.fontSize(12).text("Gaps", { underline: true });
+  doc.fontSize(10);
+
+  if (!report.assessment.gaps.length) {
+    doc.text("No gaps identified.");
+  } else {
+    for (const gap of report.assessment.gaps) {
+      doc.text(
+        `- [${gap.severity}] ${gap.gap_id} (${gap.pillar}): ${gap.description}`,
+        { lineGap: 2 },
+      );
+    }
+  }
+
+  if (report.assessment.notes) {
+    doc.moveDown(0.5);
+    doc.fontSize(12).text("Notes", { underline: true });
+    doc.fontSize(10).text(report.assessment.notes);
+  }
+
+  doc.end();
+  return bufferPromise;
+}

package/src/formatters/textFormatter.js

@@ -0,0 +1,30 @@
+function formatGap(gap, index) {
+  return `${index + 1}. [${gap.severity}] ${gap.gap_id} (${gap.pillar}) - ${gap.description}`;
+}
+
+export function formatText(report) {
+  const lines = [];
+  lines.push("ADAPT API Assessment");
+  lines.push("====================");
+  lines.push(`Spec: ${report.spec.fileName} (${report.spec.specType}, ${report.spec.sizeKb} KB)`);
+  lines.push(`Provider/Model: ${report.meta.provider}/${report.meta.model}`);
+  lines.push(`Disposition: ${report.assessment.disposition}`);
+  lines.push(`Summary: ${report.assessment.summary}`);
+  lines.push("");
+  lines.push("Gaps:");
+
+  if (!report.assessment.gaps.length) {
+    lines.push("- No gaps identified.");
+  } else {
+    report.assessment.gaps.forEach((gap, index) => {
+      lines.push(formatGap(gap, index));
+    });
+  }
+
+  if (report.assessment.notes) {
+    lines.push("");
+    lines.push(`Notes: ${report.assessment.notes}`);
+  }
+
+  return `${lines.join("\n")}\n`;
+}

package/src/utils/configStore.js

@@ -0,0 +1,80 @@
+import Conf from "conf";
+import os from "node:os";
+import path from "node:path";
+
+const configDir =
+  process.env.APIADAPT_CONFIG_DIR || path.join(os.homedir(), ".config", "apiadapt");
+
+let configInstance = null;
+
+const VALID_PROVIDERS = new Set(["ollama", "openai", "anthropic"]);
+const VALID_FORMATS = new Set(["json", "text", "pdf"]);
+
+function getConfig() {
+  if (!configInstance) {
+    configInstance = new Conf({
+      projectName: "apiadapt",
+      configName: "settings",
+      cwd: configDir,
+      defaults: {
+        llmProvider: "ollama",
+        model: "llama3.2",
+        outputFormat: "text",
+        apiKey: "",
+        baseUrl: "",
+      },
+    });
+  }
+  return configInstance;
+}
+
+export function getSettings() {
+  const config = getConfig();
+  return {
+    llmProvider: config.get("llmProvider"),
+    model: config.get("model"),
+    outputFormat: config.get("outputFormat"),
+    apiKey: config.get("apiKey"),
+    baseUrl: config.get("baseUrl"),
+  };
+}
+
+export function saveSettings(partialSettings) {
+  const config = getConfig();
+  if (partialSettings.llmProvider) {
+    const provider = String(partialSettings.llmProvider).trim().toLowerCase();
+    if (!VALID_PROVIDERS.has(provider)) {
+      throw new Error(
+        `Invalid --llm value "${partialSettings.llmProvider}". Use ollama, openai, or anthropic.`,
+      );
+    }
+    config.set("llmProvider", provider);
+  }
+
+  if (partialSettings.outputFormat) {
+    const format = String(partialSettings.outputFormat).trim().toLowerCase();
+    if (!VALID_FORMATS.has(format)) {
+      throw new Error(
+        `Invalid --format value "${partialSettings.outputFormat}". Use json, text, or pdf.`,
+      );
+    }
+    config.set("outputFormat", format);
+  }
+
+  if (partialSettings.model !== undefined) {
+    config.set("model", String(partialSettings.model).trim());
+  }
+  if (partialSettings.apiKey !== undefined) {
+    config.set("apiKey", String(partialSettings.apiKey).trim());
+  }
+  if (partialSettings.baseUrl !== undefined) {
+    config.set("baseUrl", String(partialSettings.baseUrl).trim());
+  }
+
+  return getSettings();
+}
+
+export function getConfigPath() {
+  const config = getConfig();
+  return config.path;
+}

package/src/utils/prompts.js

@@ -0,0 +1,13 @@
+import { createInterface } from "node:readline/promises";
+import { stdin as input, stdout as output } from "node:process";
+
+export async function askQuestion(question, fallback = "") {
+  const rl = createInterface({ input, output });
+  try {
+    const answer = await rl.question(question);
+    const trimmed = answer.trim();
+    return trimmed || fallback;
+  } finally {
+    rl.close();
+  }
+}

package/src/utils/specLoader.js

@@ -0,0 +1,65 @@
+import path from "node:path";
+import fs from "fs-extra";
+import yaml from "js-yaml";
+
+function inferSpecType(filePath, rawText) {
+  const lower = filePath.toLowerCase();
+  const trimmed = rawText.trimStart();
+
+  if (lower.endsWith(".raml") || trimmed.startsWith("#%RAML")) {
+    return "RAML";
+  }
+  if (lower.endsWith(".json")) {
+    return "OpenAPI (JSON)";
+  }
+  if (lower.endsWith(".yaml") || lower.endsWith(".yml")) {
+    return "OpenAPI (YAML)";
+  }
+  return "Unknown";
+}
+
+function parseSpec(rawText, specType) {
+  if (specType === "OpenAPI (JSON)") {
+    return JSON.parse(rawText);
+  }
+  if (specType === "OpenAPI (YAML)" || specType === "RAML") {
+    return yaml.load(rawText);
+  }
+
+  try {
+    return JSON.parse(rawText);
+  } catch {
+    return yaml.load(rawText);
+  }
+}
+
+export async function loadSpecFromFile(filePath) {
+  const absolutePath = path.resolve(filePath);
+  const exists = await fs.pathExists(absolutePath);
+  if (!exists) {
+    throw new Error(`Spec file not found: ${filePath}`);
+  }
+
+  const rawText = await fs.readFile(absolutePath, "utf8");
+  const specType = inferSpecType(absolutePath, rawText);
+
+  let parsed;
+  try {
+    parsed = parseSpec(rawText, specType);
+  } catch (error) {
+    throw new Error(`Invalid API spec syntax: ${error.message}`);
+  }
+
+  if (!parsed || typeof parsed !== "object") {
+    throw new Error("Invalid API spec: expected JSON or YAML object.");
+  }
+
+  return {
+    filePath: absolutePath,
+    fileName: path.basename(absolutePath),
+    specType,
+    sizeBytes: Buffer.byteLength(rawText, "utf8"),
+    rawText,
+    parsed,
+  };
+}